MoodleDocs - User contributions [en]

Setting up your development environment for the Moodle App

2022-01-26T14:27:45Z

Quen: moved the text when I realised there was an existing entry for it, oops

{{Moodle App (Ionic 5)}}
The structure of this page is the following:
* The first part, up to the point where you get the <code>npm start</code> command to work, includes the basics of what you need to work on the app.
* The second part indicates how to build the app to run it on a native device (or emulator).
* The third part includes a list of troubleshooting advice. If you encounter a problem that is not already listed, please consider adding it.

Most of your development can happen on a browser, you only need to use an emulator if you have to work on native functionality.

If you are just [[Moodle App Plugins Development Guide|adding mobile support to plugins]], you probably don't need to build the app yourself and you can skip reading this page.
== Requirements ==
===Install a browser for development===
Most of the time we recommend that you use a browser for development; the app will work in any Chromium-based browser. We recommend using the Chromium browser (an open source alternative to Google Chrome). You can get it from the [https://www.chromium.org/getting-involved/download-chromium official download page].

To learn more about using a browser for development, and why it needs to be Chromium-based, read the [[Using the Moodle App in a browser]] page.
===Install git===
You will need to install Git in order to get the source code and upload your changes. If you are not familiar with it, we recommend that you get started reading the following guide: [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git Installing Git].
===Install Node.js and Npm===
We recommend using a version manager like [https://github.com/nvm-sh/nvm nvm] to make this easier, you can prepare the correct environment running <code>nvm install</code> in the project root. Remember to run this every time you work with the app, or if you’re not working on any other node projects in your computer you can run <code>nvm alias default `node -v`</code> to make it the default.

It may seem simpler and easier to install directly from [http://nodejs.org nodejs.org], but actually it is more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to uninstall node completely before installing nvm - or search for trouble-shooting instructions online.
===Install native SDKs===
If you intend to run the application in a native device, you will need to install that platform's native SDKs. You can learn how to set up your environment by reading Ionic’s documentation for [https://ionicframework.com/docs/developing/android Android] and [https://ionicframework.com/docs/developing/ios iOS].
===Windows only: Native build dependencies===
<code>node-gyp</code> requires native build tools for your platform. If you're developing on Mac or Linux, you'll probably have these already ([https://github.com/nodejs/node-gyp/blob/master/README.md refer to the docs if you don't]). On Windows, run the following command as administrator (in cmd or Powershell):
<syntaxhighlight lang="bash">
npm install --global --production windows-build-tools
</syntaxhighlight>
Warning! This installer can take a very, very long time to run. We were seeing it take hours. Literally. Be prepared to be very patient. Don't just make the natural assumption that it has crashed.
===Mac only: Push notifications===
This is only be necessary if you intend to compile the native iOS application. The push notifications plugin requires CocoaPods to work on a Mac; you can find the complete installation instructions in [https://cocoapods.org/ the official documentation], but it should work by running the following commands:
<syntaxhighlight lang="bash">
sudo gem install cocoapods
pod setup
</syntaxhighlight>
Please note that for compiling the app in Mac you need to open the '''Moodle.xcworkspace''' file, more information here: MOBILE-1970.
===Linux only: libsecret===
If you are using [[Moodle App scripts: gulp push|the gulp push script]], you need to have <code>libsecret</code> installed before running <code>npm install</code>. Depending on your distribution, you will need to run one of the following commands:
<syntaxhighlight lang="bash">
# Debian/Ubuntu
sudo apt-get install libsecret-1-dev

# Red Hat
sudo yum install libsecret-devel

# Arch Linux
sudo pacman -S libsecret
</syntaxhighlight>
== Running the app in a browser ==
You can obtain a copy of the source code by cloning the public repository. If you want to work on the latest development version, you should check out the <code>integration</code> branch:
<syntaxhighlight lang="bash">
git clone git@github.com:moodlehq/moodleapp.git
cd moodleapp
git checkout integration
</syntaxhighlight>
Once you have the correct environment set up, you can run the application with the following two commands:
<syntaxhighlight lang="bash">
npm install
npm start
</syntaxhighlight>
This will launch the application in a browser and you should be ready to start coding (you may also want to [[Using the Moodle App in a browser#Configuring_the_default_browser|configure the default browser]] for future runs). This compiles the entire application and can take a while, so don't worry if it doesn't open the browser instantly. Keep in mind that this command may open the browser before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again. It should be ready when you see a "Compiled successfully" message in the console.

Congratulations, you have just completed the basics to become a Moodle App developer!

If you need to work with native features or build packaged versions of the app, you can read the rest of this page.

== Running the app in Android and iOS ==
The first time you want to run the application in a native device, this process will take a bit longer than usual because it needs to create the native projects and install native plugins. These will be created under the <code>platforms/</code> and <code>plugins/</code> folders respectively. If you ever run into issues during this process, try deleting both of these folders to get a clean start.

In order to run the application on a native device, you can use one of the following commands:
<syntaxhighlight lang="bash">
npm run dev:android # Uses Live Reload, read below
npm run dev:ios # Does NOT use Live Reload, read below
npm run prod:android # Uses AOT compilation, read below
npm run prod:ios # Uses AOT compilation, read below
</syntaxhighlight>
If you get any errors while building, please see the [[#Troubleshooting|Troubleshooting]] section below.
=== Developing using Live Reload ===
Most of the time, it is recommended to develop using the <code>npm start</code> command. Working in a browser is faster, easier, and doesn't have as much overhead. However, in some situations you may want to run the application in a native device. If you want a similar development experience, you'll want to enable [https://ionicframework.com/docs/cli/livereload Live Reload].

In Android, you can use the <code>npm run dev:android</code> command and the application will launch on a device or emulator. Whenever you make any changes to your code, the application will reload automatically. Keep in mind that this command may launch the application before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again (you should see "Compiled successfully" in the console).

In iOS, there are some limitations using live reload and that's why the <code>npm run dev:ios</code> command doesn't enable it by default. You can still use it by running <code>npx ionic cordova run ios --livereload --external</code>, but keep in mind that this will serve your application on an IP and will expose it to anyone connected to the same Wi-Fi network. Other than privacy concerns, this may cause some problems if you are working with iframes or local files. If you have any problems with that, you'll have to use the <code>npm run dev:ios</code> command to recompile the application every time you change the code.
=== Compiling using AOT ===
Angular has 2 ways of compiling: [https://angular.io/guide/glossary#jit JIT] and [https://angular.io/guide/glossary#aot AOT].

Running <code>npm start</code>, <code>npm run dev:android</code> or <code>npm run dev:ios</code> compiles using JIT, which is faster to compile but the app takes longer to start. This is acceptable during development because it allows you to use Live Reload.

The <code>npm run prod:android</code> and <code>npm run prod:ios</code> commands use AOT compilation because they generate production bundles.
=== Using Android emulators ===
Most of the time, you should be using an emulator running recent versions of Android, and it should work fine. But sometimes, you may want to use an older version to test a specific behaviour.

If you want to run the application in an Android 5 emulator, you’ll need to upgrade the system webview because emulators come with version 37 preinstalled. Your first idea may be to upgrade the webview using the Google Play store, but it will not work because the webview served by Google Play is <code>com.google.android.webview</code> whilst the system webview used in emulators is <code>com.android.webview</code>. You can do the following instead.

Once you have [https://developer.android.com/studio/run/managing-avds created your Android 5 virtual device], you’ll need to do download [https://android.googlesource.com/platform/external/chromium-webview/+/refs/heads/oreo-m3-release/prebuilt/x86_64/ the apk for Webview 61] and run the following commands:
<syntaxhighlight lang="bash">
# Open the folder where the “emulator” script is installed
cd $(dirname `which emulator`)

# Boot the emulator in write mode
# (you can get a list of device names running “emulator -list-avds”)
emulator @DeviceName -writable-system

# In a different shell, make /system writable
adb remount

# Uninstall the webview app manually and reboot the device
adb shell
rm -rf /data/data/com.android.webview
rm -rf /system/app/webview
reboot

# Install the new version
adb install webview.apk
</syntaxhighlight>
After doing this, remember to run the emulator in write mode for subsequent sessions, but you don’t need to call the <code>remount</code> command every time.
== Troubleshooting ==
This section contains a list of common errors that have been found and how to solve them. However, keep in mind that these may be platform-dependent and could not fix the problem in your machine, even if you are seeing the same error message.
=== General advice ===
If you are stuck with an error and you can't find a way to continue, here's a list of things you can do:
* Using git, look at the changes you have in your working directory and make sure that they aren't causing the problem. Be specially careful with changes in <code>package.json</code> and <code>package-lock.json</code>. You can see a list of the files you have modified running <code>git status</code>.
* Make sure that you are using the proper node and npm versions. You can see it looking at the <code>engines</code> key in <code>package.json</code>. If you are using [https://github.com/nvm-sh/nvm nvm], just run <code>nvm install</code>.
* Make sure that all dependencies have been installed properly. To be extra sure, run <code>npm ci</code>; this will remove the <code>node_modules/</code> folder and install all dependencies again exactly as described in your <code>package-lock.json</code>.
* If you are having issues trying to build for Android or iOS, try removing the <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> folders and try again.
* If you are using a development version, maybe the repository is broken and it's not your fault. Try checking out the <code>master</code> branch and see if you're getting the same error.
* Try cloning the repository in a new folder and run through the instructions in this page again. If you can, try doing it on a different computer to make sure that you're doing everything properly and it's not a problem in your machine.
* Try creating [https://ionicframework.com/docs/cli/commands/start a blank Ionic application] and see if you're having the same problems. Make sure that you are using the same version of the main dependencies (Angular, Cordova, Ionic CLI, etc.).
* If you are searching for help online, maybe your problem has nothing to do with the Moodle App in particular an it's related with Ionic, Cordova, Angular, etc. Searching using the proper context will give you better solutions.
=== I get a blank page when launching the app ===
This error can happen when the application is launched properly but there is a runtime error. If you get a network connection error, this may be the expected behaviour. Wait until you see "Compiled successfully" in the console and reload.

If that's not the case and you really are getting a blank page, look at the console and you should see some error indicating why the application is not rendering properly. Keep in mind that at the moment the application is already logging some errors and warnings, so make sure that you're not stuck trying to fix something that isn't causing the problem. You can follow any updates about this on MOBILE-3854.

If you are not seeing any relevant logs, check out what to do on the [[#General_advice|General advice]] section.
=== Strange NPM errors ===
To get more debug output from npm commands, see [https://docs.npmjs.com/cli/v7/using-npm/config the available configuration flags]. In particular try adding <code>--loglevel verbose</code>, <code>--loglevel info</code> or <code>--loglevel silly</code> to the command-line.
=== I can't change the language ===
If you're getting a network error for a url like <code><nowiki>http://localhost:8100/assets/lang/es.json</nowiki></code>, this probably means that you haven't installed the language packs.

Currently, you can install them in your machine running the <code>scripts/update_lang.sh</code> script, but it may not work in your system if you don't have php installed. For future improvements, you can subscribe to MOBILE-3864.
=== Error: libsass bindings not found. Try reinstalling node-sass? ===
Most of the time, running the following command will fix the problem:
<syntaxhighlight lang="bash">
npm rebuild node-sass
</syntaxhighlight>
=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}
</syntaxhighlight>
=== 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.
=== Could not find com.android.support:support-v4:XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}
</syntaxhighlight>
=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}
</syntaxhighlight>
=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===
Download [https://developer.android.com/studio/ Android Studio] and copy the folder <code>android-studio/plugins/android/lib/templates</code> into <code>android-sdk-folder/Sdk/tools</code>.
=== Could not find com.android.support:support-v4:27.1.0 ===
Open the file <code>platforms/android/build.gradle</code> and configure like this:
<syntaxhighlight lang="groovy">
allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}
</syntaxhighlight>
=== Error: not found: make ===
If you see this error in Ubuntu, run <code>sudo apt-get install build-essential</code> and retry.
=== Current working directory is not a Cordova-based project. ===
If you see this error during <code>npm start</code>, run <code>mkdir www</code> and retry.
=== ReferenceError: internalBinding is not defined ===
This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with <code>natives</code> prior to 1.1.6. It can be fixed by running <code>npm install natives@1.1.6</code>.
=== npm update check failed ===
You may get the following error on Windows:
<syntaxhighlight lang="bash">
│ npm update check failed │
│ Try running with sudo or get access │
│ to the local update config store via │
│ sudo chown -R $USER:$(id -gn $USER) C:\Users\username\.config │
</syntaxhighlight>
The suggested command does not work on Windows, so the solution is to manually check the ownership of all the files in <code>C:\Users\{username}\.config\configstore</code>. In some cases, it can be <code>update-notifier-npm.json</code> that got changed to be owned by Administrator.
=== Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ... ===
This is a common issue for Cygwin user running Node. However, you just need to ensure that Msysgit is on your windows path and that the cygwin bin folder is not. Then always use another shell like Powershell for your Moodle App development.

You don't need your Cygwin bin folder on the Windows path because it automatically gets added to the path when you lauch Cygwin bash.
=== The product name change (<name> tag) in config.xml is not supported dynamically ===
This happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. The solution seems to be removing and adding the iOS platform again:
<syntaxhighlight lang="bash">
npx ionic platform remove ios
npx ionic platform add ios
</syntaxhighlight>
===Failed to install 'cordova-plugin-x' ===
Sometimes, you may see an error message similar to this:
<syntaxhighlight lang="bash">
CordovaError: Version of installed plugin: "cordova-plugin-x@x.x.x" does not satisfy dependency plugin requirement "cordova-plugin-x@>=x.x.x".
</syntaxhighlight>
This can happen when a cordova plugin (let's call it "X") is installed with an incorrect version. You can find this by removing the plugin and adding it again with the correct version:
<syntaxhighlight lang="bash">
npx cordova plugin remove cordova-plugin-x
npx cordova plugin add cordova-plugin-x@x.x.x # Make sure to use the proper version here
</syntaxhighlight>
Please notice that if there is any plugin installed that depends on <code>cordova-plugin-x</code> you'll have to remove and re-add them too.
=== doc.find is not a function ===
This happens in some environments, the solution is to run <code>npx cordova platform add ios</code> before running the failing command. You should do this in a clean environment, once you've seen the error running the command may not work. Try deleting <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> before trying again.

[https://stackoverflow.com/questions/47404622/edit-config-for-ios-usage-descriptions-doc-find-is-not-a-function Find more about this in StackOverflow]
===Mac: linker code failed with exit code 1===
If you get this error when trying to build the Moodle app with XCode, some dependencies might not have installed correctly.

Ensure you have followed the [#Mac_only:_Push_notifications Mac only: Push notifications] steps above (particularly opening the .xcworkspace file rather than the .xcodeproj file). Then run the following:
<syntaxhighlight lang="bash">
cd platforms/ios
pod install
</syntaxhighlight>
Now try running the build again in XCode.
===Windows: <code>npm start</code> hangs after "Starting 'watch'"===

If you follow the above procedure to run the app on a Windows system and get repeated 'Waiting for connectivity with NPM' like this:

<pre>
$ npm start

> moodlemobile@3.9.5 start C:\Users\xxx\workspace\moodlemobile2
> ionic serve

> npm.cmd run ionic:serve:before

> moodlemobile@3.9.5 ionic:serve:before C:\Users\xxx\workspace\moodlemobile2
> gulp

[13:59:24] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[13:59:24] Starting 'default'...
[13:59:24] Starting 'lang'...
[13:59:24] Starting 'env'...
[13:59:25] Finished 'env' after 802 ms
[13:59:27] Finished 'lang' after 3.4 s
[13:59:27] Finished 'default' after 3.4 s
> npm.cmd run ionic:serve -- --host=localhost --port=8100 --project=app
[npm] > moodlemobile@3.9.5 ionic:serve C:\Users\xxx\workspace\moodlemobile2
[npm] > gulp watch & NODE_OPTIONS=--max-old-space-size=4096 ng serve "--host=localhost" "--port=8100" "--project=app"
[INFO] Waiting for connectivity with npm...
[npm] [13:59:46] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[npm] [13:59:46] Starting 'watch'...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
</pre>

You can resolve the problem (sort of) by pressing ctrl-c to get out of it, then rerun the last command displayed, but this time with 'npx' before each of the 2 commands. (This assumes you are using a bash shell.)

<syntaxhighlight lang="bash">
npx gulp watch & NODE_OPTIONS=--max-old-space-size=4096 npx ng serve "--host=localhost" "--port=8100" "--project=app"
</syntaxhighlight>

There will be a pause (a few minutes) while building everything. It should finish with the line:

<tt>
: Compiled successfully.
</tt>

Then you can access it by running Chrome and connecting to localhost:8100.

== See also ==
* [[Moodle App Coding Style]]
* [[Debugging network requests in the Moodle_App]]
* [https://github.com/moodlehq/moodle-docker Moodle Docker]
* [http://ionicframework.com/docs/cli/ Ionic CLI docs]

Setting up your development environment for the Moodle App

2022-01-26T14:23:11Z

Quen: /* Windows 'Waiting for connectivity with NPM' problem */

{{Moodle App (Ionic 5)}}
The structure of this page is the following:
* The first part, up to the point where you get the <code>npm start</code> command to work, includes the basics of what you need to work on the app.
* The second part indicates how to build the app to run it on a native device (or emulator).
* The third part includes a list of troubleshooting advice. If you encounter a problem that is not already listed, please consider adding it.

Most of your development can happen on a browser, you only need to use an emulator if you have to work on native functionality.

If you are just [[Moodle App Plugins Development Guide|adding mobile support to plugins]], you probably don't need to build the app yourself and you can skip reading this page.
== Requirements ==
===Install a browser for development===
Most of the time we recommend that you use a browser for development; the app will work in any Chromium-based browser. We recommend using the Chromium browser (an open source alternative to Google Chrome). You can get it from the [https://www.chromium.org/getting-involved/download-chromium official download page].

To learn more about using a browser for development, and why it needs to be Chromium-based, read the [[Using the Moodle App in a browser]] page.
===Install git===
You will need to install Git in order to get the source code and upload your changes. If you are not familiar with it, we recommend that you get started reading the following guide: [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git Installing Git].
===Install Node.js and Npm===
We recommend using a version manager like [https://github.com/nvm-sh/nvm nvm] to make this easier, you can prepare the correct environment running <code>nvm install</code> in the project root. Remember to run this every time you work with the app, or if you’re not working on any other node projects in your computer you can run <code>nvm alias default `node -v`</code> to make it the default.

It may seem simpler and easier to install directly from [http://nodejs.org nodejs.org], but actually it is more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to uninstall node completely before installing nvm - or search for trouble-shooting instructions online.
===Install native SDKs===
If you intend to run the application in a native device, you will need to install that platform's native SDKs. You can learn how to set up your environment by reading Ionic’s documentation for [https://ionicframework.com/docs/developing/android Android] and [https://ionicframework.com/docs/developing/ios iOS].
===Windows only: Native build dependencies===
<code>node-gyp</code> requires native build tools for your platform. If you're developing on Mac or Linux, you'll probably have these already ([https://github.com/nodejs/node-gyp/blob/master/README.md refer to the docs if you don't]). On Windows, run the following command as administrator (in cmd or Powershell):
<syntaxhighlight lang="bash">
npm install --global --production windows-build-tools
</syntaxhighlight>
Warning! This installer can take a very, very long time to run. We were seeing it take hours. Literally. Be prepared to be very patient. Don't just make the natural assumption that it has crashed.
===Mac only: Push notifications===
This is only be necessary if you intend to compile the native iOS application. The push notifications plugin requires CocoaPods to work on a Mac; you can find the complete installation instructions in [https://cocoapods.org/ the official documentation], but it should work by running the following commands:
<syntaxhighlight lang="bash">
sudo gem install cocoapods
pod setup
</syntaxhighlight>
Please note that for compiling the app in Mac you need to open the '''Moodle.xcworkspace''' file, more information here: MOBILE-1970.
===Linux only: libsecret===
If you are using [[Moodle App scripts: gulp push|the gulp push script]], you need to have <code>libsecret</code> installed before running <code>npm install</code>. Depending on your distribution, you will need to run one of the following commands:
<syntaxhighlight lang="bash">
# Debian/Ubuntu
sudo apt-get install libsecret-1-dev

# Red Hat
sudo yum install libsecret-devel

# Arch Linux
sudo pacman -S libsecret
</syntaxhighlight>
== Running the app in a browser ==
You can obtain a copy of the source code by cloning the public repository. If you want to work on the latest development version, you should check out the <code>integration</code> branch:
<syntaxhighlight lang="bash">
git clone git@github.com:moodlehq/moodleapp.git
cd moodleapp
git checkout integration
</syntaxhighlight>
Once you have the correct environment set up, you can run the application with the following two commands:
<syntaxhighlight lang="bash">
npm install
npm start
</syntaxhighlight>
This will launch the application in a browser and you should be ready to start coding (you may also want to [[Using the Moodle App in a browser#Configuring_the_default_browser|configure the default browser]] for future runs). This compiles the entire application and can take a while, so don't worry if it doesn't open the browser instantly. Keep in mind that this command may open the browser before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again. It should be ready when you see a "Compiled successfully" message in the console.

Congratulations, you have just completed the basics to become a Moodle App developer!

If you need to work with native features or build packaged versions of the app, you can read the rest of this page.

=== Windows 'Waiting for connectivity with NPM' problem ===

If you follow the above procedure on a Windows system (may depend on installed versions etc.) and get repeated 'Waiting for connectivity with NPM' like this:

<pre>
$ npm start

> moodlemobile@3.9.5 start C:\Users\xxx\workspace\moodlemobile2
> ionic serve

> npm.cmd run ionic:serve:before

> moodlemobile@3.9.5 ionic:serve:before C:\Users\xxx\workspace\moodlemobile2
> gulp

[13:59:24] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[13:59:24] Starting 'default'...
[13:59:24] Starting 'lang'...
[13:59:24] Starting 'env'...
[13:59:25] Finished 'env' after 802 ms
[13:59:27] Finished 'lang' after 3.4 s
[13:59:27] Finished 'default' after 3.4 s
> npm.cmd run ionic:serve -- --host=localhost --port=8100 --project=app
[npm] > moodlemobile@3.9.5 ionic:serve C:\Users\xxx\workspace\moodlemobile2
[npm] > gulp watch & NODE_OPTIONS=--max-old-space-size=4096 ng serve "--host=localhost" "--port=8100" "--project=app"
[INFO] Waiting for connectivity with npm...
[npm] [13:59:46] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[npm] [13:59:46] Starting 'watch'...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
</pre>

You can resolve the problem (sort of) by pressing ctrl-c to get out of it, then rerun the last command displayed, but this time with 'npx' before each of the 2 commands. (This assumes you are using a bash shell.)

<syntaxhighlight lang="bash">
npx gulp watch & NODE_OPTIONS=--max-old-space-size=4096 npx ng serve "--host=localhost" "--port=8100" "--project=app"
</syntaxhighlight>

There will be a pause (a few minutes) while building everything. It should finish with the line:

<tt>
: Compiled successfully.
</tt>

Then you can access it by running Chrome and connecting to localhost:8100.

== Running the app in Android and iOS ==
The first time you want to run the application in a native device, this process will take a bit longer than usual because it needs to create the native projects and install native plugins. These will be created under the <code>platforms/</code> and <code>plugins/</code> folders respectively. If you ever run into issues during this process, try deleting both of these folders to get a clean start.

In order to run the application on a native device, you can use one of the following commands:
<syntaxhighlight lang="bash">
npm run dev:android # Uses Live Reload, read below
npm run dev:ios # Does NOT use Live Reload, read below
npm run prod:android # Uses AOT compilation, read below
npm run prod:ios # Uses AOT compilation, read below
</syntaxhighlight>
If you get any errors while building, please see the [[#Troubleshooting|Troubleshooting]] section below.
=== Developing using Live Reload ===
Most of the time, it is recommended to develop using the <code>npm start</code> command. Working in a browser is faster, easier, and doesn't have as much overhead. However, in some situations you may want to run the application in a native device. If you want a similar development experience, you'll want to enable [https://ionicframework.com/docs/cli/livereload Live Reload].

In Android, you can use the <code>npm run dev:android</code> command and the application will launch on a device or emulator. Whenever you make any changes to your code, the application will reload automatically. Keep in mind that this command may launch the application before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again (you should see "Compiled successfully" in the console).

In iOS, there are some limitations using live reload and that's why the <code>npm run dev:ios</code> command doesn't enable it by default. You can still use it by running <code>npx ionic cordova run ios --livereload --external</code>, but keep in mind that this will serve your application on an IP and will expose it to anyone connected to the same Wi-Fi network. Other than privacy concerns, this may cause some problems if you are working with iframes or local files. If you have any problems with that, you'll have to use the <code>npm run dev:ios</code> command to recompile the application every time you change the code.
=== Compiling using AOT ===
Angular has 2 ways of compiling: [https://angular.io/guide/glossary#jit JIT] and [https://angular.io/guide/glossary#aot AOT].

Running <code>npm start</code>, <code>npm run dev:android</code> or <code>npm run dev:ios</code> compiles using JIT, which is faster to compile but the app takes longer to start. This is acceptable during development because it allows you to use Live Reload.

The <code>npm run prod:android</code> and <code>npm run prod:ios</code> commands use AOT compilation because they generate production bundles.
=== Using Android emulators ===
Most of the time, you should be using an emulator running recent versions of Android, and it should work fine. But sometimes, you may want to use an older version to test a specific behaviour.

If you want to run the application in an Android 5 emulator, you’ll need to upgrade the system webview because emulators come with version 37 preinstalled. Your first idea may be to upgrade the webview using the Google Play store, but it will not work because the webview served by Google Play is <code>com.google.android.webview</code> whilst the system webview used in emulators is <code>com.android.webview</code>. You can do the following instead.

Once you have [https://developer.android.com/studio/run/managing-avds created your Android 5 virtual device], you’ll need to do download [https://android.googlesource.com/platform/external/chromium-webview/+/refs/heads/oreo-m3-release/prebuilt/x86_64/ the apk for Webview 61] and run the following commands:
<syntaxhighlight lang="bash">
# Open the folder where the “emulator” script is installed
cd $(dirname `which emulator`)

# Boot the emulator in write mode
# (you can get a list of device names running “emulator -list-avds”)
emulator @DeviceName -writable-system

# In a different shell, make /system writable
adb remount

# Uninstall the webview app manually and reboot the device
adb shell
rm -rf /data/data/com.android.webview
rm -rf /system/app/webview
reboot

# Install the new version
adb install webview.apk
</syntaxhighlight>
After doing this, remember to run the emulator in write mode for subsequent sessions, but you don’t need to call the <code>remount</code> command every time.
== Troubleshooting ==
This section contains a list of common errors that have been found and how to solve them. However, keep in mind that these may be platform-dependent and could not fix the problem in your machine, even if you are seeing the same error message.
=== General advice ===
If you are stuck with an error and you can't find a way to continue, here's a list of things you can do:
* Using git, look at the changes you have in your working directory and make sure that they aren't causing the problem. Be specially careful with changes in <code>package.json</code> and <code>package-lock.json</code>. You can see a list of the files you have modified running <code>git status</code>.
* Make sure that you are using the proper node and npm versions. You can see it looking at the <code>engines</code> key in <code>package.json</code>. If you are using [https://github.com/nvm-sh/nvm nvm], just run <code>nvm install</code>.
* Make sure that all dependencies have been installed properly. To be extra sure, run <code>npm ci</code>; this will remove the <code>node_modules/</code> folder and install all dependencies again exactly as described in your <code>package-lock.json</code>.
* If you are having issues trying to build for Android or iOS, try removing the <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> folders and try again.
* If you are using a development version, maybe the repository is broken and it's not your fault. Try checking out the <code>master</code> branch and see if you're getting the same error.
* Try cloning the repository in a new folder and run through the instructions in this page again. If you can, try doing it on a different computer to make sure that you're doing everything properly and it's not a problem in your machine.
* Try creating [https://ionicframework.com/docs/cli/commands/start a blank Ionic application] and see if you're having the same problems. Make sure that you are using the same version of the main dependencies (Angular, Cordova, Ionic CLI, etc.).
* If you are searching for help online, maybe your problem has nothing to do with the Moodle App in particular an it's related with Ionic, Cordova, Angular, etc. Searching using the proper context will give you better solutions.
=== I get a blank page when launching the app ===
This error can happen when the application is launched properly but there is a runtime error. If you get a network connection error, this may be the expected behaviour. Wait until you see "Compiled successfully" in the console and reload.

If that's not the case and you really are getting a blank page, look at the console and you should see some error indicating why the application is not rendering properly. Keep in mind that at the moment the application is already logging some errors and warnings, so make sure that you're not stuck trying to fix something that isn't causing the problem. You can follow any updates about this on MOBILE-3854.

If you are not seeing any relevant logs, check out what to do on the [[#General_advice|General advice]] section.
=== Strange NPM errors ===
To get more debug output from npm commands, see [https://docs.npmjs.com/cli/v7/using-npm/config the available configuration flags]. In particular try adding <code>--loglevel verbose</code>, <code>--loglevel info</code> or <code>--loglevel silly</code> to the command-line.
=== I can't change the language ===
If you're getting a network error for a url like <code><nowiki>http://localhost:8100/assets/lang/es.json</nowiki></code>, this probably means that you haven't installed the language packs.

Currently, you can install them in your machine running the <code>scripts/update_lang.sh</code> script, but it may not work in your system if you don't have php installed. For future improvements, you can subscribe to MOBILE-3864.
=== Error: libsass bindings not found. Try reinstalling node-sass? ===
Most of the time, running the following command will fix the problem:
<syntaxhighlight lang="bash">
npm rebuild node-sass
</syntaxhighlight>
=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}
</syntaxhighlight>
=== 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.
=== Could not find com.android.support:support-v4:XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}
</syntaxhighlight>
=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}
</syntaxhighlight>
=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===
Download [https://developer.android.com/studio/ Android Studio] and copy the folder <code>android-studio/plugins/android/lib/templates</code> into <code>android-sdk-folder/Sdk/tools</code>.
=== Could not find com.android.support:support-v4:27.1.0 ===
Open the file <code>platforms/android/build.gradle</code> and configure like this:
<syntaxhighlight lang="groovy">
allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}
</syntaxhighlight>
=== Error: not found: make ===
If you see this error in Ubuntu, run <code>sudo apt-get install build-essential</code> and retry.
=== Current working directory is not a Cordova-based project. ===
If you see this error during <code>npm start</code>, run <code>mkdir www</code> and retry.
=== ReferenceError: internalBinding is not defined ===
This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with <code>natives</code> prior to 1.1.6. It can be fixed by running <code>npm install natives@1.1.6</code>.
=== npm update check failed ===
You may get the following error on Windows:
<syntaxhighlight lang="bash">
│ npm update check failed │
│ Try running with sudo or get access │
│ to the local update config store via │
│ sudo chown -R $USER:$(id -gn $USER) C:\Users\username\.config │
</syntaxhighlight>
The suggested command does not work on Windows, so the solution is to manually check the ownership of all the files in <code>C:\Users\{username}\.config\configstore</code>. In some cases, it can be <code>update-notifier-npm.json</code> that got changed to be owned by Administrator.
=== Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ... ===
This is a common issue for Cygwin user running Node. However, you just need to ensure that Msysgit is on your windows path and that the cygwin bin folder is not. Then always use another shell like Powershell for your Moodle App development.

You don't need your Cygwin bin folder on the Windows path because it automatically gets added to the path when you lauch Cygwin bash.
=== The product name change (<name> tag) in config.xml is not supported dynamically ===
This happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. The solution seems to be removing and adding the iOS platform again:
<syntaxhighlight lang="bash">
npx ionic platform remove ios
npx ionic platform add ios
</syntaxhighlight>
===Failed to install 'cordova-plugin-x' ===
Sometimes, you may see an error message similar to this:
<syntaxhighlight lang="bash">
CordovaError: Version of installed plugin: "cordova-plugin-x@x.x.x" does not satisfy dependency plugin requirement "cordova-plugin-x@>=x.x.x".
</syntaxhighlight>
This can happen when a cordova plugin (let's call it "X") is installed with an incorrect version. You can find this by removing the plugin and adding it again with the correct version:
<syntaxhighlight lang="bash">
npx cordova plugin remove cordova-plugin-x
npx cordova plugin add cordova-plugin-x@x.x.x # Make sure to use the proper version here
</syntaxhighlight>
Please notice that if there is any plugin installed that depends on <code>cordova-plugin-x</code> you'll have to remove and re-add them too.
=== doc.find is not a function ===
This happens in some environments, the solution is to run <code>npx cordova platform add ios</code> before running the failing command. You should do this in a clean environment, once you've seen the error running the command may not work. Try deleting <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> before trying again.

[https://stackoverflow.com/questions/47404622/edit-config-for-ios-usage-descriptions-doc-find-is-not-a-function Find more about this in StackOverflow]
===Mac: linker code failed with exit code 1===
If you get this error when trying to build the Moodle app with XCode, some dependencies might not have installed correctly.

Ensure you have followed the [#Mac_only:_Push_notifications Mac only: Push notifications] steps above (particularly opening the .xcworkspace file rather than the .xcodeproj file). Then run the following:
<syntaxhighlight lang="bash">
cd platforms/ios
pod install
</syntaxhighlight>
Now try running the build again in XCode.
===Windows: <code>npm start</code> hangs after "Starting 'watch'"===
Try running the commands generated by <code>npm start</code> directly in bash:
<syntaxhighlight lang="bash">
npx gulp watch & NODE_OPTIONS=--max-old-space-size=4096 npx ng serve "--host=0.0.0.0" "--port=8100" "--project=app"
</syntaxhighlight>
== See also ==
* [[Moodle App Coding Style]]
* [[Debugging network requests in the Moodle_App]]
* [https://github.com/moodlehq/moodle-docker Moodle Docker]
* [http://ionicframework.com/docs/cli/ Ionic CLI docs]

Setting up your development environment for the Moodle App

2022-01-26T14:22:23Z

Quen: /* Windows 'Waiting for connectivity with NPM' problem */

{{Moodle App (Ionic 5)}}
The structure of this page is the following:
* The first part, up to the point where you get the <code>npm start</code> command to work, includes the basics of what you need to work on the app.
* The second part indicates how to build the app to run it on a native device (or emulator).
* The third part includes a list of troubleshooting advice. If you encounter a problem that is not already listed, please consider adding it.

Most of your development can happen on a browser, you only need to use an emulator if you have to work on native functionality.

If you are just [[Moodle App Plugins Development Guide|adding mobile support to plugins]], you probably don't need to build the app yourself and you can skip reading this page.
== Requirements ==
===Install a browser for development===
Most of the time we recommend that you use a browser for development; the app will work in any Chromium-based browser. We recommend using the Chromium browser (an open source alternative to Google Chrome). You can get it from the [https://www.chromium.org/getting-involved/download-chromium official download page].

To learn more about using a browser for development, and why it needs to be Chromium-based, read the [[Using the Moodle App in a browser]] page.
===Install git===
You will need to install Git in order to get the source code and upload your changes. If you are not familiar with it, we recommend that you get started reading the following guide: [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git Installing Git].
===Install Node.js and Npm===
We recommend using a version manager like [https://github.com/nvm-sh/nvm nvm] to make this easier, you can prepare the correct environment running <code>nvm install</code> in the project root. Remember to run this every time you work with the app, or if you’re not working on any other node projects in your computer you can run <code>nvm alias default `node -v`</code> to make it the default.

It may seem simpler and easier to install directly from [http://nodejs.org nodejs.org], but actually it is more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to uninstall node completely before installing nvm - or search for trouble-shooting instructions online.
===Install native SDKs===
If you intend to run the application in a native device, you will need to install that platform's native SDKs. You can learn how to set up your environment by reading Ionic’s documentation for [https://ionicframework.com/docs/developing/android Android] and [https://ionicframework.com/docs/developing/ios iOS].
===Windows only: Native build dependencies===
<code>node-gyp</code> requires native build tools for your platform. If you're developing on Mac or Linux, you'll probably have these already ([https://github.com/nodejs/node-gyp/blob/master/README.md refer to the docs if you don't]). On Windows, run the following command as administrator (in cmd or Powershell):
<syntaxhighlight lang="bash">
npm install --global --production windows-build-tools
</syntaxhighlight>
Warning! This installer can take a very, very long time to run. We were seeing it take hours. Literally. Be prepared to be very patient. Don't just make the natural assumption that it has crashed.
===Mac only: Push notifications===
This is only be necessary if you intend to compile the native iOS application. The push notifications plugin requires CocoaPods to work on a Mac; you can find the complete installation instructions in [https://cocoapods.org/ the official documentation], but it should work by running the following commands:
<syntaxhighlight lang="bash">
sudo gem install cocoapods
pod setup
</syntaxhighlight>
Please note that for compiling the app in Mac you need to open the '''Moodle.xcworkspace''' file, more information here: MOBILE-1970.
===Linux only: libsecret===
If you are using [[Moodle App scripts: gulp push|the gulp push script]], you need to have <code>libsecret</code> installed before running <code>npm install</code>. Depending on your distribution, you will need to run one of the following commands:
<syntaxhighlight lang="bash">
# Debian/Ubuntu
sudo apt-get install libsecret-1-dev

# Red Hat
sudo yum install libsecret-devel

# Arch Linux
sudo pacman -S libsecret
</syntaxhighlight>
== Running the app in a browser ==
You can obtain a copy of the source code by cloning the public repository. If you want to work on the latest development version, you should check out the <code>integration</code> branch:
<syntaxhighlight lang="bash">
git clone git@github.com:moodlehq/moodleapp.git
cd moodleapp
git checkout integration
</syntaxhighlight>
Once you have the correct environment set up, you can run the application with the following two commands:
<syntaxhighlight lang="bash">
npm install
npm start
</syntaxhighlight>
This will launch the application in a browser and you should be ready to start coding (you may also want to [[Using the Moodle App in a browser#Configuring_the_default_browser|configure the default browser]] for future runs). This compiles the entire application and can take a while, so don't worry if it doesn't open the browser instantly. Keep in mind that this command may open the browser before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again. It should be ready when you see a "Compiled successfully" message in the console.

Congratulations, you have just completed the basics to become a Moodle App developer!

If you need to work with native features or build packaged versions of the app, you can read the rest of this page.

=== Windows 'Waiting for connectivity with NPM' problem ===

If you follow the above procedure on a Windows system (may depend on installed versions etc.) and get repeated 'Waiting for connectivity with NPM' like this:

<pre>
$ npm start

> moodlemobile@3.9.5 start C:\Users\xxx\workspace\moodlemobile2
> ionic serve

> npm.cmd run ionic:serve:before

> moodlemobile@3.9.5 ionic:serve:before C:\Users\xxx\workspace\moodlemobile2
> gulp

[13:59:24] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[13:59:24] Starting 'default'...
[13:59:24] Starting 'lang'...
[13:59:24] Starting 'env'...
[13:59:25] Finished 'env' after 802 ms
[13:59:27] Finished 'lang' after 3.4 s
[13:59:27] Finished 'default' after 3.4 s
> npm.cmd run ionic:serve -- --host=localhost --port=8100 --project=app
[npm] > moodlemobile@3.9.5 ionic:serve C:\Users\xxx\workspace\moodlemobile2
[npm] > gulp watch & NODE_OPTIONS=--max-old-space-size=4096 ng serve "--host=localhost" "--port=8100" "--project=app"
[INFO] Waiting for connectivity with npm...
[npm] [13:59:46] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[npm] [13:59:46] Starting 'watch'...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
</pre>

You can resolve the problem (sort of) by pressing ctrl-c to get out of it, then rerun the last command displayed, but this time with 'npx' before each of the 2 commands. (This assumes you are using a bash shell.)

<syntaxhighlight lang="bash">
npx gulp watch & NODE_OPTIONS=--max-old-space-size=4096 npx ng serve "--host=localhost" "--port=8100" "--project=app"
</syntaxhighlight>

There will be a pause (a few minutes) while building everything. It should finish with the lines:

<tt>
** Angular Live Development Server is listening on localhost:8100, open your browser on http://localhost:8100/ **
: Compiled successfully.
</tt>

Then you can access it by running Chrome and connecting to localhost:8100.

== Running the app in Android and iOS ==
The first time you want to run the application in a native device, this process will take a bit longer than usual because it needs to create the native projects and install native plugins. These will be created under the <code>platforms/</code> and <code>plugins/</code> folders respectively. If you ever run into issues during this process, try deleting both of these folders to get a clean start.

In order to run the application on a native device, you can use one of the following commands:
<syntaxhighlight lang="bash">
npm run dev:android # Uses Live Reload, read below
npm run dev:ios # Does NOT use Live Reload, read below
npm run prod:android # Uses AOT compilation, read below
npm run prod:ios # Uses AOT compilation, read below
</syntaxhighlight>
If you get any errors while building, please see the [[#Troubleshooting|Troubleshooting]] section below.
=== Developing using Live Reload ===
Most of the time, it is recommended to develop using the <code>npm start</code> command. Working in a browser is faster, easier, and doesn't have as much overhead. However, in some situations you may want to run the application in a native device. If you want a similar development experience, you'll want to enable [https://ionicframework.com/docs/cli/livereload Live Reload].

In Android, you can use the <code>npm run dev:android</code> command and the application will launch on a device or emulator. Whenever you make any changes to your code, the application will reload automatically. Keep in mind that this command may launch the application before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again (you should see "Compiled successfully" in the console).

In iOS, there are some limitations using live reload and that's why the <code>npm run dev:ios</code> command doesn't enable it by default. You can still use it by running <code>npx ionic cordova run ios --livereload --external</code>, but keep in mind that this will serve your application on an IP and will expose it to anyone connected to the same Wi-Fi network. Other than privacy concerns, this may cause some problems if you are working with iframes or local files. If you have any problems with that, you'll have to use the <code>npm run dev:ios</code> command to recompile the application every time you change the code.
=== Compiling using AOT ===
Angular has 2 ways of compiling: [https://angular.io/guide/glossary#jit JIT] and [https://angular.io/guide/glossary#aot AOT].

Running <code>npm start</code>, <code>npm run dev:android</code> or <code>npm run dev:ios</code> compiles using JIT, which is faster to compile but the app takes longer to start. This is acceptable during development because it allows you to use Live Reload.

The <code>npm run prod:android</code> and <code>npm run prod:ios</code> commands use AOT compilation because they generate production bundles.
=== Using Android emulators ===
Most of the time, you should be using an emulator running recent versions of Android, and it should work fine. But sometimes, you may want to use an older version to test a specific behaviour.

If you want to run the application in an Android 5 emulator, you’ll need to upgrade the system webview because emulators come with version 37 preinstalled. Your first idea may be to upgrade the webview using the Google Play store, but it will not work because the webview served by Google Play is <code>com.google.android.webview</code> whilst the system webview used in emulators is <code>com.android.webview</code>. You can do the following instead.

Once you have [https://developer.android.com/studio/run/managing-avds created your Android 5 virtual device], you’ll need to do download [https://android.googlesource.com/platform/external/chromium-webview/+/refs/heads/oreo-m3-release/prebuilt/x86_64/ the apk for Webview 61] and run the following commands:
<syntaxhighlight lang="bash">
# Open the folder where the “emulator” script is installed
cd $(dirname `which emulator`)

# Boot the emulator in write mode
# (you can get a list of device names running “emulator -list-avds”)
emulator @DeviceName -writable-system

# In a different shell, make /system writable
adb remount

# Uninstall the webview app manually and reboot the device
adb shell
rm -rf /data/data/com.android.webview
rm -rf /system/app/webview
reboot

# Install the new version
adb install webview.apk
</syntaxhighlight>
After doing this, remember to run the emulator in write mode for subsequent sessions, but you don’t need to call the <code>remount</code> command every time.
== Troubleshooting ==
This section contains a list of common errors that have been found and how to solve them. However, keep in mind that these may be platform-dependent and could not fix the problem in your machine, even if you are seeing the same error message.
=== General advice ===
If you are stuck with an error and you can't find a way to continue, here's a list of things you can do:
* Using git, look at the changes you have in your working directory and make sure that they aren't causing the problem. Be specially careful with changes in <code>package.json</code> and <code>package-lock.json</code>. You can see a list of the files you have modified running <code>git status</code>.
* Make sure that you are using the proper node and npm versions. You can see it looking at the <code>engines</code> key in <code>package.json</code>. If you are using [https://github.com/nvm-sh/nvm nvm], just run <code>nvm install</code>.
* Make sure that all dependencies have been installed properly. To be extra sure, run <code>npm ci</code>; this will remove the <code>node_modules/</code> folder and install all dependencies again exactly as described in your <code>package-lock.json</code>.
* If you are having issues trying to build for Android or iOS, try removing the <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> folders and try again.
* If you are using a development version, maybe the repository is broken and it's not your fault. Try checking out the <code>master</code> branch and see if you're getting the same error.
* Try cloning the repository in a new folder and run through the instructions in this page again. If you can, try doing it on a different computer to make sure that you're doing everything properly and it's not a problem in your machine.
* Try creating [https://ionicframework.com/docs/cli/commands/start a blank Ionic application] and see if you're having the same problems. Make sure that you are using the same version of the main dependencies (Angular, Cordova, Ionic CLI, etc.).
* If you are searching for help online, maybe your problem has nothing to do with the Moodle App in particular an it's related with Ionic, Cordova, Angular, etc. Searching using the proper context will give you better solutions.
=== I get a blank page when launching the app ===
This error can happen when the application is launched properly but there is a runtime error. If you get a network connection error, this may be the expected behaviour. Wait until you see "Compiled successfully" in the console and reload.

If that's not the case and you really are getting a blank page, look at the console and you should see some error indicating why the application is not rendering properly. Keep in mind that at the moment the application is already logging some errors and warnings, so make sure that you're not stuck trying to fix something that isn't causing the problem. You can follow any updates about this on MOBILE-3854.

If you are not seeing any relevant logs, check out what to do on the [[#General_advice|General advice]] section.
=== Strange NPM errors ===
To get more debug output from npm commands, see [https://docs.npmjs.com/cli/v7/using-npm/config the available configuration flags]. In particular try adding <code>--loglevel verbose</code>, <code>--loglevel info</code> or <code>--loglevel silly</code> to the command-line.
=== I can't change the language ===
If you're getting a network error for a url like <code><nowiki>http://localhost:8100/assets/lang/es.json</nowiki></code>, this probably means that you haven't installed the language packs.

Currently, you can install them in your machine running the <code>scripts/update_lang.sh</code> script, but it may not work in your system if you don't have php installed. For future improvements, you can subscribe to MOBILE-3864.
=== Error: libsass bindings not found. Try reinstalling node-sass? ===
Most of the time, running the following command will fix the problem:
<syntaxhighlight lang="bash">
npm rebuild node-sass
</syntaxhighlight>
=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}
</syntaxhighlight>
=== 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.
=== Could not find com.android.support:support-v4:XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}
</syntaxhighlight>
=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}
</syntaxhighlight>
=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===
Download [https://developer.android.com/studio/ Android Studio] and copy the folder <code>android-studio/plugins/android/lib/templates</code> into <code>android-sdk-folder/Sdk/tools</code>.
=== Could not find com.android.support:support-v4:27.1.0 ===
Open the file <code>platforms/android/build.gradle</code> and configure like this:
<syntaxhighlight lang="groovy">
allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}
</syntaxhighlight>
=== Error: not found: make ===
If you see this error in Ubuntu, run <code>sudo apt-get install build-essential</code> and retry.
=== Current working directory is not a Cordova-based project. ===
If you see this error during <code>npm start</code>, run <code>mkdir www</code> and retry.
=== ReferenceError: internalBinding is not defined ===
This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with <code>natives</code> prior to 1.1.6. It can be fixed by running <code>npm install natives@1.1.6</code>.
=== npm update check failed ===
You may get the following error on Windows:
<syntaxhighlight lang="bash">
│ npm update check failed │
│ Try running with sudo or get access │
│ to the local update config store via │
│ sudo chown -R $USER:$(id -gn $USER) C:\Users\username\.config │
</syntaxhighlight>
The suggested command does not work on Windows, so the solution is to manually check the ownership of all the files in <code>C:\Users\{username}\.config\configstore</code>. In some cases, it can be <code>update-notifier-npm.json</code> that got changed to be owned by Administrator.
=== Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ... ===
This is a common issue for Cygwin user running Node. However, you just need to ensure that Msysgit is on your windows path and that the cygwin bin folder is not. Then always use another shell like Powershell for your Moodle App development.

You don't need your Cygwin bin folder on the Windows path because it automatically gets added to the path when you lauch Cygwin bash.
=== The product name change (<name> tag) in config.xml is not supported dynamically ===
This happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. The solution seems to be removing and adding the iOS platform again:
<syntaxhighlight lang="bash">
npx ionic platform remove ios
npx ionic platform add ios
</syntaxhighlight>
===Failed to install 'cordova-plugin-x' ===
Sometimes, you may see an error message similar to this:
<syntaxhighlight lang="bash">
CordovaError: Version of installed plugin: "cordova-plugin-x@x.x.x" does not satisfy dependency plugin requirement "cordova-plugin-x@>=x.x.x".
</syntaxhighlight>
This can happen when a cordova plugin (let's call it "X") is installed with an incorrect version. You can find this by removing the plugin and adding it again with the correct version:
<syntaxhighlight lang="bash">
npx cordova plugin remove cordova-plugin-x
npx cordova plugin add cordova-plugin-x@x.x.x # Make sure to use the proper version here
</syntaxhighlight>
Please notice that if there is any plugin installed that depends on <code>cordova-plugin-x</code> you'll have to remove and re-add them too.
=== doc.find is not a function ===
This happens in some environments, the solution is to run <code>npx cordova platform add ios</code> before running the failing command. You should do this in a clean environment, once you've seen the error running the command may not work. Try deleting <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> before trying again.

[https://stackoverflow.com/questions/47404622/edit-config-for-ios-usage-descriptions-doc-find-is-not-a-function Find more about this in StackOverflow]
===Mac: linker code failed with exit code 1===
If you get this error when trying to build the Moodle app with XCode, some dependencies might not have installed correctly.

Ensure you have followed the [#Mac_only:_Push_notifications Mac only: Push notifications] steps above (particularly opening the .xcworkspace file rather than the .xcodeproj file). Then run the following:
<syntaxhighlight lang="bash">
cd platforms/ios
pod install
</syntaxhighlight>
Now try running the build again in XCode.
===Windows: <code>npm start</code> hangs after "Starting 'watch'"===
Try running the commands generated by <code>npm start</code> directly in bash:
<syntaxhighlight lang="bash">
npx gulp watch & NODE_OPTIONS=--max-old-space-size=4096 npx ng serve "--host=0.0.0.0" "--port=8100" "--project=app"
</syntaxhighlight>
== See also ==
* [[Moodle App Coding Style]]
* [[Debugging network requests in the Moodle_App]]
* [https://github.com/moodlehq/moodle-docker Moodle Docker]
* [http://ionicframework.com/docs/cli/ Ionic CLI docs]

Setting up your development environment for the Moodle App

2022-01-26T14:21:49Z

Quen: /* Running the app in a browser */

{{Moodle App (Ionic 5)}}
The structure of this page is the following:
* The first part, up to the point where you get the <code>npm start</code> command to work, includes the basics of what you need to work on the app.
* The second part indicates how to build the app to run it on a native device (or emulator).
* The third part includes a list of troubleshooting advice. If you encounter a problem that is not already listed, please consider adding it.

Most of your development can happen on a browser, you only need to use an emulator if you have to work on native functionality.

If you are just [[Moodle App Plugins Development Guide|adding mobile support to plugins]], you probably don't need to build the app yourself and you can skip reading this page.
== Requirements ==
===Install a browser for development===
Most of the time we recommend that you use a browser for development; the app will work in any Chromium-based browser. We recommend using the Chromium browser (an open source alternative to Google Chrome). You can get it from the [https://www.chromium.org/getting-involved/download-chromium official download page].

To learn more about using a browser for development, and why it needs to be Chromium-based, read the [[Using the Moodle App in a browser]] page.
===Install git===
You will need to install Git in order to get the source code and upload your changes. If you are not familiar with it, we recommend that you get started reading the following guide: [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git Installing Git].
===Install Node.js and Npm===
We recommend using a version manager like [https://github.com/nvm-sh/nvm nvm] to make this easier, you can prepare the correct environment running <code>nvm install</code> in the project root. Remember to run this every time you work with the app, or if you’re not working on any other node projects in your computer you can run <code>nvm alias default `node -v`</code> to make it the default.

It may seem simpler and easier to install directly from [http://nodejs.org nodejs.org], but actually it is more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to uninstall node completely before installing nvm - or search for trouble-shooting instructions online.
===Install native SDKs===
If you intend to run the application in a native device, you will need to install that platform's native SDKs. You can learn how to set up your environment by reading Ionic’s documentation for [https://ionicframework.com/docs/developing/android Android] and [https://ionicframework.com/docs/developing/ios iOS].
===Windows only: Native build dependencies===
<code>node-gyp</code> requires native build tools for your platform. If you're developing on Mac or Linux, you'll probably have these already ([https://github.com/nodejs/node-gyp/blob/master/README.md refer to the docs if you don't]). On Windows, run the following command as administrator (in cmd or Powershell):
<syntaxhighlight lang="bash">
npm install --global --production windows-build-tools
</syntaxhighlight>
Warning! This installer can take a very, very long time to run. We were seeing it take hours. Literally. Be prepared to be very patient. Don't just make the natural assumption that it has crashed.
===Mac only: Push notifications===
This is only be necessary if you intend to compile the native iOS application. The push notifications plugin requires CocoaPods to work on a Mac; you can find the complete installation instructions in [https://cocoapods.org/ the official documentation], but it should work by running the following commands:
<syntaxhighlight lang="bash">
sudo gem install cocoapods
pod setup
</syntaxhighlight>
Please note that for compiling the app in Mac you need to open the '''Moodle.xcworkspace''' file, more information here: MOBILE-1970.
===Linux only: libsecret===
If you are using [[Moodle App scripts: gulp push|the gulp push script]], you need to have <code>libsecret</code> installed before running <code>npm install</code>. Depending on your distribution, you will need to run one of the following commands:
<syntaxhighlight lang="bash">
# Debian/Ubuntu
sudo apt-get install libsecret-1-dev

# Red Hat
sudo yum install libsecret-devel

# Arch Linux
sudo pacman -S libsecret
</syntaxhighlight>
== Running the app in a browser ==
You can obtain a copy of the source code by cloning the public repository. If you want to work on the latest development version, you should check out the <code>integration</code> branch:
<syntaxhighlight lang="bash">
git clone git@github.com:moodlehq/moodleapp.git
cd moodleapp
git checkout integration
</syntaxhighlight>
Once you have the correct environment set up, you can run the application with the following two commands:
<syntaxhighlight lang="bash">
npm install
npm start
</syntaxhighlight>
This will launch the application in a browser and you should be ready to start coding (you may also want to [[Using the Moodle App in a browser#Configuring_the_default_browser|configure the default browser]] for future runs). This compiles the entire application and can take a while, so don't worry if it doesn't open the browser instantly. Keep in mind that this command may open the browser before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again. It should be ready when you see a "Compiled successfully" message in the console.

Congratulations, you have just completed the basics to become a Moodle App developer!

If you need to work with native features or build packaged versions of the app, you can read the rest of this page.

=== Windows 'Waiting for connectivity with NPM' problem ===

If you follow the above procedure on a Windows system (may depend on installed versions etc.) and get repeated 'Waiting for connectivity with NPM' like this:

<pre>
$ npm start

> moodlemobile@3.9.5 start C:\Users\sm449\workspace\moodlemobile2
> ionic serve

> npm.cmd run ionic:serve:before

> moodlemobile@3.9.5 ionic:serve:before C:\Users\sm449\workspace\moodlemobile2
> gulp

[13:59:24] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[13:59:24] Starting 'default'...
[13:59:24] Starting 'lang'...
[13:59:24] Starting 'env'...
[13:59:25] Finished 'env' after 802 ms
[13:59:27] Finished 'lang' after 3.4 s
[13:59:27] Finished 'default' after 3.4 s
> npm.cmd run ionic:serve -- --host=localhost --port=8100 --project=app
[npm] > moodlemobile@3.9.5 ionic:serve C:\Users\sm449\workspace\moodlemobile2
[npm] > gulp watch & NODE_OPTIONS=--max-old-space-size=4096 ng serve "--host=localhost" "--port=8100" "--project=app"
[INFO] Waiting for connectivity with npm...
[npm] [13:59:46] Using gulpfile ~\workspace\moodlemobile2\gulpfile.js
[npm] [13:59:46] Starting 'watch'...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
[INFO] Waiting for connectivity with npm...
</pre>

You can resolve the problem (sort of) by pressing ctrl-c to get out of it, then rerun the last command displayed, but this time with 'npx' before each of the 2 commands. (This assumes you are using a bash shell.)

<syntaxhighlight lang="bash">
npx gulp watch & NODE_OPTIONS=--max-old-space-size=4096 npx ng serve "--host=localhost" "--port=8100" "--project=app"
</syntaxhighlight>

There will be a pause (a few minutes) while building everything. It should finish with the lines:

<tt>
** Angular Live Development Server is listening on localhost:8100, open your browser on http://localhost:8100/ **
: Compiled successfully.
</tt>

Then you can access it by running Chrome and connecting to localhost:8100.

== Running the app in Android and iOS ==
The first time you want to run the application in a native device, this process will take a bit longer than usual because it needs to create the native projects and install native plugins. These will be created under the <code>platforms/</code> and <code>plugins/</code> folders respectively. If you ever run into issues during this process, try deleting both of these folders to get a clean start.

In order to run the application on a native device, you can use one of the following commands:
<syntaxhighlight lang="bash">
npm run dev:android # Uses Live Reload, read below
npm run dev:ios # Does NOT use Live Reload, read below
npm run prod:android # Uses AOT compilation, read below
npm run prod:ios # Uses AOT compilation, read below
</syntaxhighlight>
If you get any errors while building, please see the [[#Troubleshooting|Troubleshooting]] section below.
=== Developing using Live Reload ===
Most of the time, it is recommended to develop using the <code>npm start</code> command. Working in a browser is faster, easier, and doesn't have as much overhead. However, in some situations you may want to run the application in a native device. If you want a similar development experience, you'll want to enable [https://ionicframework.com/docs/cli/livereload Live Reload].

In Android, you can use the <code>npm run dev:android</code> command and the application will launch on a device or emulator. Whenever you make any changes to your code, the application will reload automatically. Keep in mind that this command may launch the application before the dev server is ready, and you could get a network error. If that happens, just wait until the dev server is ready and launch the application again (you should see "Compiled successfully" in the console).

In iOS, there are some limitations using live reload and that's why the <code>npm run dev:ios</code> command doesn't enable it by default. You can still use it by running <code>npx ionic cordova run ios --livereload --external</code>, but keep in mind that this will serve your application on an IP and will expose it to anyone connected to the same Wi-Fi network. Other than privacy concerns, this may cause some problems if you are working with iframes or local files. If you have any problems with that, you'll have to use the <code>npm run dev:ios</code> command to recompile the application every time you change the code.
=== Compiling using AOT ===
Angular has 2 ways of compiling: [https://angular.io/guide/glossary#jit JIT] and [https://angular.io/guide/glossary#aot AOT].

Running <code>npm start</code>, <code>npm run dev:android</code> or <code>npm run dev:ios</code> compiles using JIT, which is faster to compile but the app takes longer to start. This is acceptable during development because it allows you to use Live Reload.

The <code>npm run prod:android</code> and <code>npm run prod:ios</code> commands use AOT compilation because they generate production bundles.
=== Using Android emulators ===
Most of the time, you should be using an emulator running recent versions of Android, and it should work fine. But sometimes, you may want to use an older version to test a specific behaviour.

If you want to run the application in an Android 5 emulator, you’ll need to upgrade the system webview because emulators come with version 37 preinstalled. Your first idea may be to upgrade the webview using the Google Play store, but it will not work because the webview served by Google Play is <code>com.google.android.webview</code> whilst the system webview used in emulators is <code>com.android.webview</code>. You can do the following instead.

Once you have [https://developer.android.com/studio/run/managing-avds created your Android 5 virtual device], you’ll need to do download [https://android.googlesource.com/platform/external/chromium-webview/+/refs/heads/oreo-m3-release/prebuilt/x86_64/ the apk for Webview 61] and run the following commands:
<syntaxhighlight lang="bash">
# Open the folder where the “emulator” script is installed
cd $(dirname `which emulator`)

# Boot the emulator in write mode
# (you can get a list of device names running “emulator -list-avds”)
emulator @DeviceName -writable-system

# In a different shell, make /system writable
adb remount

# Uninstall the webview app manually and reboot the device
adb shell
rm -rf /data/data/com.android.webview
rm -rf /system/app/webview
reboot

# Install the new version
adb install webview.apk
</syntaxhighlight>
After doing this, remember to run the emulator in write mode for subsequent sessions, but you don’t need to call the <code>remount</code> command every time.
== Troubleshooting ==
This section contains a list of common errors that have been found and how to solve them. However, keep in mind that these may be platform-dependent and could not fix the problem in your machine, even if you are seeing the same error message.
=== General advice ===
If you are stuck with an error and you can't find a way to continue, here's a list of things you can do:
* Using git, look at the changes you have in your working directory and make sure that they aren't causing the problem. Be specially careful with changes in <code>package.json</code> and <code>package-lock.json</code>. You can see a list of the files you have modified running <code>git status</code>.
* Make sure that you are using the proper node and npm versions. You can see it looking at the <code>engines</code> key in <code>package.json</code>. If you are using [https://github.com/nvm-sh/nvm nvm], just run <code>nvm install</code>.
* Make sure that all dependencies have been installed properly. To be extra sure, run <code>npm ci</code>; this will remove the <code>node_modules/</code> folder and install all dependencies again exactly as described in your <code>package-lock.json</code>.
* If you are having issues trying to build for Android or iOS, try removing the <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> folders and try again.
* If you are using a development version, maybe the repository is broken and it's not your fault. Try checking out the <code>master</code> branch and see if you're getting the same error.
* Try cloning the repository in a new folder and run through the instructions in this page again. If you can, try doing it on a different computer to make sure that you're doing everything properly and it's not a problem in your machine.
* Try creating [https://ionicframework.com/docs/cli/commands/start a blank Ionic application] and see if you're having the same problems. Make sure that you are using the same version of the main dependencies (Angular, Cordova, Ionic CLI, etc.).
* If you are searching for help online, maybe your problem has nothing to do with the Moodle App in particular an it's related with Ionic, Cordova, Angular, etc. Searching using the proper context will give you better solutions.
=== I get a blank page when launching the app ===
This error can happen when the application is launched properly but there is a runtime error. If you get a network connection error, this may be the expected behaviour. Wait until you see "Compiled successfully" in the console and reload.

If that's not the case and you really are getting a blank page, look at the console and you should see some error indicating why the application is not rendering properly. Keep in mind that at the moment the application is already logging some errors and warnings, so make sure that you're not stuck trying to fix something that isn't causing the problem. You can follow any updates about this on MOBILE-3854.

If you are not seeing any relevant logs, check out what to do on the [[#General_advice|General advice]] section.
=== Strange NPM errors ===
To get more debug output from npm commands, see [https://docs.npmjs.com/cli/v7/using-npm/config the available configuration flags]. In particular try adding <code>--loglevel verbose</code>, <code>--loglevel info</code> or <code>--loglevel silly</code> to the command-line.
=== I can't change the language ===
If you're getting a network error for a url like <code><nowiki>http://localhost:8100/assets/lang/es.json</nowiki></code>, this probably means that you haven't installed the language packs.

Currently, you can install them in your machine running the <code>scripts/update_lang.sh</code> script, but it may not work in your system if you don't have php installed. For future improvements, you can subscribe to MOBILE-3864.
=== Error: libsass bindings not found. Try reinstalling node-sass? ===
Most of the time, running the following command will fix the problem:
<syntaxhighlight lang="bash">
npm rebuild node-sass
</syntaxhighlight>
=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}
</syntaxhighlight>
=== 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.
=== Could not find com.android.support:support-v4:XXX ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}
</syntaxhighlight>
=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===
Open the file <code>platforms/android/build.gradle</code> and add this code at the end:
<syntaxhighlight lang="groovy">
android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}
</syntaxhighlight>
=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===
Download [https://developer.android.com/studio/ Android Studio] and copy the folder <code>android-studio/plugins/android/lib/templates</code> into <code>android-sdk-folder/Sdk/tools</code>.
=== Could not find com.android.support:support-v4:27.1.0 ===
Open the file <code>platforms/android/build.gradle</code> and configure like this:
<syntaxhighlight lang="groovy">
allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}
</syntaxhighlight>
=== Error: not found: make ===
If you see this error in Ubuntu, run <code>sudo apt-get install build-essential</code> and retry.
=== Current working directory is not a Cordova-based project. ===
If you see this error during <code>npm start</code>, run <code>mkdir www</code> and retry.
=== ReferenceError: internalBinding is not defined ===
This [https://stackoverflow.com/questions/53146394/node-app-fails-to-run-on-mojave-referenceerror-internalbinding-is-not-defined seems to be] an error with <code>natives</code> prior to 1.1.6. It can be fixed by running <code>npm install natives@1.1.6</code>.
=== npm update check failed ===
You may get the following error on Windows:
<syntaxhighlight lang="bash">
│ npm update check failed │
│ Try running with sudo or get access │
│ to the local update config store via │
│ sudo chown -R $USER:$(id -gn $USER) C:\Users\username\.config │
</syntaxhighlight>
The suggested command does not work on Windows, so the solution is to manually check the ownership of all the files in <code>C:\Users\{username}\.config\configstore</code>. In some cases, it can be <code>update-notifier-npm.json</code> that got changed to be owned by Administrator.
=== Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ... ===
This is a common issue for Cygwin user running Node. However, you just need to ensure that Msysgit is on your windows path and that the cygwin bin folder is not. Then always use another shell like Powershell for your Moodle App development.

You don't need your Cygwin bin folder on the Windows path because it automatically gets added to the path when you lauch Cygwin bash.
=== The product name change (<name> tag) in config.xml is not supported dynamically ===
This happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. The solution seems to be removing and adding the iOS platform again:
<syntaxhighlight lang="bash">
npx ionic platform remove ios
npx ionic platform add ios
</syntaxhighlight>
===Failed to install 'cordova-plugin-x' ===
Sometimes, you may see an error message similar to this:
<syntaxhighlight lang="bash">
CordovaError: Version of installed plugin: "cordova-plugin-x@x.x.x" does not satisfy dependency plugin requirement "cordova-plugin-x@>=x.x.x".
</syntaxhighlight>
This can happen when a cordova plugin (let's call it "X") is installed with an incorrect version. You can find this by removing the plugin and adding it again with the correct version:
<syntaxhighlight lang="bash">
npx cordova plugin remove cordova-plugin-x
npx cordova plugin add cordova-plugin-x@x.x.x # Make sure to use the proper version here
</syntaxhighlight>
Please notice that if there is any plugin installed that depends on <code>cordova-plugin-x</code> you'll have to remove and re-add them too.
=== doc.find is not a function ===
This happens in some environments, the solution is to run <code>npx cordova platform add ios</code> before running the failing command. You should do this in a clean environment, once you've seen the error running the command may not work. Try deleting <code>www/</code>, <code>platforms/</code> and <code>plugins/</code> before trying again.

[https://stackoverflow.com/questions/47404622/edit-config-for-ios-usage-descriptions-doc-find-is-not-a-function Find more about this in StackOverflow]
===Mac: linker code failed with exit code 1===
If you get this error when trying to build the Moodle app with XCode, some dependencies might not have installed correctly.

Ensure you have followed the [#Mac_only:_Push_notifications Mac only: Push notifications] steps above (particularly opening the .xcworkspace file rather than the .xcodeproj file). Then run the following:
<syntaxhighlight lang="bash">
cd platforms/ios
pod install
</syntaxhighlight>
Now try running the build again in XCode.
===Windows: <code>npm start</code> hangs after "Starting 'watch'"===
Try running the commands generated by <code>npm start</code> directly in bash:
<syntaxhighlight lang="bash">
npx gulp watch & NODE_OPTIONS=--max-old-space-size=4096 npx ng serve "--host=0.0.0.0" "--port=8100" "--project=app"
</syntaxhighlight>
== See also ==
* [[Moodle App Coding Style]]
* [[Debugging network requests in the Moodle_App]]
* [https://github.com/moodlehq/moodle-docker Moodle Docker]
* [http://ionicframework.com/docs/cli/ Ionic CLI docs]

User fields

2021-03-29T12:40:31Z

Quen:

{{Moodle 3.11}}

Code relating to display of user fields is in the class <tt>\core_user\fields</tt> in file <tt>/user/classes/fields.php</tt>.

* See also [[User-related APIs]], which has information about defining custom user fields.

== Overview ==

This class is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This class supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core_user\fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core_user\fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core_user\fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core_user\fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC", [], 0, 10);
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can create SQL snippets for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core_user\fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-29T12:40:14Z

Quen: Updated for new location of class

{{Moodle 3.11}}

Code relating to display of user fields is in the class <tt>\core_user\fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

* See also [[User-related APIs]], which has information about defining custom user fields.

== Overview ==

This class is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This class supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core_user\fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core_user\fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core_user\fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core_user\fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC", [], 0, 10);
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can create SQL snippets for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core_user\fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User-related APIs

2021-03-11T15:30:29Z

Quen:

== Overview ==

This is a collection of miscellaneous APIs that can help with doing things with lists of users. Note that, in many cases, the more specific [[Access API]], [[Groups API]], [[Enrolment API]], etc. may be what you need.

== User field display ==

The [[User fields]] class is mainly used when displaying tables of data about users. It indicates which extra fields (e.g. email) should be displayed in the current context based on the permissions of the current user. It also provides ways to get the necessary data from a query, and to obtainother generally-useful fields for user names and pictures.

== User fields definition ==

{{Moodle 3.1}}
To guarantee the sanity of the data inserted into Moodle and avoid security bugs, new user fields definition methods have been created for use in Moodle 3.1 onwards. The purpose of these new methods is to create a central point of user fields data validation and guarantee all data inserted into Moodle will be cleaned against the correct parameter type. Another goal of this new API is to create consistency across Moodle core and avoid different parameter validations for the same user fields. For now on, user data must validate against the user field, not using clean_param() directly.

===$propertiescache===
Cached information of each user field and its attributes filled by the fill_properties_cache.

===fill_properties_cache()===
The main method of the user definition is to keep the definition of each user field and its properties. It verifies if the '''core_user::$propertiescache''' is already filled and caches all user fields attributes into this same attribute.
Each field matches the exact field name on the user table. That said, every new field added to the user table should be added to fill_properties_cache $fields array, otherwise it won't be validated or cleaned.
Each field has four possible properties, being choices and default optional:

* '''null''' - Whether the field is NULL or NOT_NULL, it SHOULD NOT be used as form validation, as many fields in the user table have NOT_NULL property but have the default value as (``).
* '''type''' - The expected parameter type (PARAM_*) to be used as validation and sanitizing.
* '''choices''' - A list of accepted values of that field. For example the list of the available countries, timezones, calendar type etc.
* '''default''' - The default value in case the user field didn't pass the validation or cleaned and we must set the default value. For example if the user country is invalid and it is not in the list of choices, set $CFG->country.

===validate()===
A static method to validate user fields, accepts an array or the user object as parameter, validate each parameter individually and can return true if all user data is correct or an array of validation errors. The purpose of this method is to just validate the user data, it won’t do any cleaning of the data.

===clean_data()===
A static method that has the purpose of clean the user data and return the same user array/object. It receives an array with user data or a user object as parameter and it checks if the data is in the list of choices and if the property has a default value and clean the data if the user object doesn’t have a choices property.
It will display a debugging message if one the operations above has problems.

===clean_field()===
A static method to clean a single user field. It has two parameters, the data to be cleaned and its user field. The behaviour of the method is similar to the clean_data. It will do the validations and cleaning and can display a debug message if an error has been found. It returns the cleaned data.

===get_property_type()===
A helper method to get the type of the property. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return its type.

===get_property_null()===
A helper method to get the null property of the user field. It receives the user field name as parameter and if it doesn't exist it throws an exception. If the property has been found, it will return the null value.

===get_property_choices()===
A helper method to get the list of choices of a user field. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return the list of accepted values.

===get_property_default()===
A helper method to get the default value of a property. It receives the user field name as parameter and if it doesn't exist or if it doesn't have a default attribute will throw an exception. If the property has been found, it will return its default value.

== User selector ==

The base class <tt>user_selector_base</tt> defined in <tt>user/selector/lib.php</tt>, which you can subclass to make a widget that lets you select users in an AJAX-y way. It is used, for example, on the Add group members page. The best way to learn how to use it is to search the code for other users, and see how they work. The base class also has good PHPdoc comments.

== Sorting lists of users ==

When you fetch a list of users from the database, they should always be sorted consistently, by using the <tt>users_order_by_sql</tt> function to generate the order-by clause. Again, the best way to see how that works is to search the code for existing uses.

== Others ==

''Please add more..''

==See also==

* [[Core APIs]]
* [[Access API]]
* [[Groups API]]
* [[Enrolment API]]

[[Category:API]]

User fields

2021-03-11T12:54:52Z

Quen:

{{Moodle 3.11}}

Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

* See also [[User-related APIs]], which has information about defining custom user fields.

== Overview ==

This class is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This class supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC", [], 0, 10);
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can create SQL snippets for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T12:54:40Z

Quen:

{{Moodle 3.11}}

Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

* See also [[User-related APIs]] which has information about defining custom user fields.

== Overview ==

This class is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This class supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC", [], 0, 10);
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can create SQL snippets for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T12:47:06Z

Quen:

{{Moodle 3.11}}

Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

== Overview ==

This class is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This class supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC", [], 0, 10);
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can create SQL snippets for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User-related APIs

2021-03-11T12:46:11Z

Quen:

== Overview ==

This is a collection of miscellaneous APIs that can help with doing things with lists of users. Note that, in many cases, the more specific [[Access API]], [[Groups API]], [[Enrolment API]], etc. may be what you need.

== User field display ==

The [[User fields API]] is mainly used when displaying tables of data about users. It indicates which extra fields (e.g. email) should be displayed in the current context based on the permissions of the current user. It also provides ways to get the necessary data from a query, and to obtainother generally-useful fields for user names and pictures.

== User fields definition ==

{{Moodle 3.1}}
To guarantee the sanity of the data inserted into Moodle and avoid security bugs, new user fields definition methods have been created for use in Moodle 3.1 onwards. The purpose of these new methods is to create a central point of user fields data validation and guarantee all data inserted into Moodle will be cleaned against the correct parameter type. Another goal of this new API is to create consistency across Moodle core and avoid different parameter validations for the same user fields. For now on, user data must validate against the user field, not using clean_param() directly.

===$propertiescache===
Cached information of each user field and its attributes filled by the fill_properties_cache.

===fill_properties_cache()===
The main method of the user definition is to keep the definition of each user field and its properties. It verifies if the '''core_user::$propertiescache''' is already filled and caches all user fields attributes into this same attribute.
Each field matches the exact field name on the user table. That said, every new field added to the user table should be added to fill_properties_cache $fields array, otherwise it won't be validated or cleaned.
Each field has four possible properties, being choices and default optional:

* '''null''' - Whether the field is NULL or NOT_NULL, it SHOULD NOT be used as form validation, as many fields in the user table have NOT_NULL property but have the default value as (``).
* '''type''' - The expected parameter type (PARAM_*) to be used as validation and sanitizing.
* '''choices''' - A list of accepted values of that field. For example the list of the available countries, timezones, calendar type etc.
* '''default''' - The default value in case the user field didn't pass the validation or cleaned and we must set the default value. For example if the user country is invalid and it is not in the list of choices, set $CFG->country.

===validate()===
A static method to validate user fields, accepts an array or the user object as parameter, validate each parameter individually and can return true if all user data is correct or an array of validation errors. The purpose of this method is to just validate the user data, it won’t do any cleaning of the data.

===clean_data()===
A static method that has the purpose of clean the user data and return the same user array/object. It receives an array with user data or a user object as parameter and it checks if the data is in the list of choices and if the property has a default value and clean the data if the user object doesn’t have a choices property.
It will display a debugging message if one the operations above has problems.

===clean_field()===
A static method to clean a single user field. It has two parameters, the data to be cleaned and its user field. The behaviour of the method is similar to the clean_data. It will do the validations and cleaning and can display a debug message if an error has been found. It returns the cleaned data.

===get_property_type()===
A helper method to get the type of the property. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return its type.

===get_property_null()===
A helper method to get the null property of the user field. It receives the user field name as parameter and if it doesn't exist it throws an exception. If the property has been found, it will return the null value.

===get_property_choices()===
A helper method to get the list of choices of a user field. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return the list of accepted values.

===get_property_default()===
A helper method to get the default value of a property. It receives the user field name as parameter and if it doesn't exist or if it doesn't have a default attribute will throw an exception. If the property has been found, it will return its default value.

== User selector ==

The base class <tt>user_selector_base</tt> defined in <tt>user/selector/lib.php</tt>, which you can subclass to make a widget that lets you select users in an AJAX-y way. It is used, for example, on the Add group members page. The best way to learn how to use it is to search the code for other users, and see how they work. The base class also has good PHPdoc comments.

== Sorting lists of users ==

When you fetch a list of users from the database, they should always be sorted consistently, by using the <tt>users_order_by_sql</tt> function to generate the order-by clause. Again, the best way to see how that works is to search the code for existing uses.

== Others ==

''Please add more..''

==See also==

* [[Core APIs]]
* [[Access API]]
* [[Groups API]]
* [[Enrolment API]]

[[Category:API]]

Core APIs

2021-03-11T12:45:40Z

Quen:

Moodle has a number of core APIs that provide tools for Moodle scripts.

They are essential when writing [[Plugins|Moodle plugins]].

==Most-used General APIs==

These APIs are critical and will be used by nearly every Moodle plugin.

=== Access API (access) ===

The [[Access API]] gives you functions so you can determine what the current user is allowed to do, and it allows modules to extend Moodle with new capabilities.

=== Data manipulation API (dml) ===

The [[Data manipulation API]] allows you to read/write to databases in a consistent and safe way.

=== File API (files) ===

The [[File API]] controls the storage of files in connection to various plugins.

=== Form API (form) ===

The [[Form API]] defines and handles user data via web forms.

=== Logging API (log) ===

The [[Events API]] allows you to log events in Moodle, while [[Logging 2]] describes how logs are stored and retrieved.

=== Navigation API (navigation) ===

The [[Navigation API]] allows you to manipulate the navigation tree to add and remove items as you wish.

=== Page API (page) ===

The [[Page API]] is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

=== Output API (output) ===

The [[Output API]] is used to render the HTML for all parts of the page.

=== String API (string) ===

The [[String API]] is how you get language text strings to use in the user interface. It handles any language translations that might be available.

=== Upgrade API (upgrade) ===

The [[Upgrade API]] is how your module installs and upgrades itself, by keeping track of its own version.

=== Moodlelib API (core) ===

The [[Moodlelib API]] is the central library file of miscellaneous general-purpose Moodle functions. Functions can over the handling of request parameters, configs, user preferences, time, login, mnet, plugins, strings and others. There are plenty of defined constants too.

==Other General APIs==

=== Admin settings API (admin) ===

The [[Admin settings]] API deals with providing configuration options for each plugin and Moodle core.

=== Analytics API (analytics) ===

The [[Analytics API]] allow you to create prediction models and generate insights.

=== Availability API (availability) ===

The [[Availability API]] controls access to activities and sections.

=== Backup API (backup) ===

The [[Backup API]] defines exactly how to convert course data into XML for backup purposes, and the [[Restore API]] describes how to convert it back the other way.

=== Cache API (cache) ===

The [[The Moodle Universal Cache (MUC)]] is the structure for storing cache data within Moodle. [[Cache_API]] explains some of what is needed to use a cache in your code.

=== Calendar API (calendar) ===

The [[Calendar API]] allows you to add and modify events in the calendar for user, groups, courses, or the whole site.

=== Check API (check) ===

The [[Check API]] allows you to add security, performance or health checks to your site.

=== Comment API (comment) ===

The [[Comment API]] allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.

=== Competency API (competency) ===

The [[Competency API]] allows you to list and add evidence of competencies to learning plans, learning plan templates, frameworks, courses and activities.

=== Data definition API (ddl) ===

The [[Data definition API]] is what you use to create, change and delete tables and fields in the database during upgrades.

=== Editor API ===

The [[Editor API]] is used to control HTML text editors.

=== Enrolment API (enrol) ===

The [[Enrolment API]] deals with course participants.

=== Events API (event) ===

The [[Events API]] allows to define "events" with payload data to be fired whenever you like, and it also allows you to define handlers to react to these events when they happen. This is the recommended form of inter-plugin communication. This also forms the basis for logging in Moodle.

=== Experience API (xAPI) ===

The Experience API (xAPI) is an e-learning standard that allows learning content and learning systems to speak to each other. The [[Experience API (xAPI)]]
allows any plugin to generate and handle xAPI standard statements.

=== External functions API (external) ===

The [[External functions API]] allows you to create fully parametrised methods that can be accessed by external programs (such as [[Web services]]).

=== Favourites API ===

The [[Favourites API]] allows you to mark items as favourites for a user and manage these favourites. This is often referred to as 'Starred'.

=== Lock API (lock) ===

The [[Lock API]] lets you synchronise processing between multiple requests, even for separate nodes in a cluster.

=== Message API (message) ===

The [[Message API]] lets you post messages to users. They decide how they want to receive them.

=== Media API (media) ===

The [[Media_players#Using_media_players|Media]] API can be used to embed media items such as audio, video, and Flash.

=== My profile API ===

The [[My profile API]] is used to add things to the profile page.

=== OAuth 2 API (oauth2) ===

The [[OAuth 2 API]] is used to provide a common place to configure and manage external systems using OAuth 2.

=== Payment API (payment) ===

The [[Payment API]] deals with payments.

=== Preference API (preference) ===

The [[Preference API]] is a simple way to store and retrieve preferences for individual users.

=== Portfolio API (portfolio) ===

The [[Portfolio API]] allows you to add portfolio interfaces on your pages and allows users to package up data to send to their portfolios.

=== Privacy API (privacy) ===

The [[Privacy API]] allows you to describe the personal data that you store, and provides the means for that data to be discovered, exported, and deleted on a per-user basis.
This allows compliance with regulation such as the General Data Protection Regulation (GDPR) in Europe.

=== Rating API (rating) ===

The [[Rating API]] lets you create AJAX rating interfaces so that users can rate items in your plugin. In an activity module, you may choose to aggregate ratings to form grades.

=== RSS API (rss) ===

The [[RSS API]] allows you to create secure RSS feeds of data in your module.

=== Search API (search) ===

The [[Search API]] allows you to index contents in a search engine and query the search engine for results.

=== Tag API (tag) ===

The [[Tag API]] allows you to store tags (and a tag cloud) to items in your module.

=== Task API (task) ===

The [[Task API]] lets you run jobs in the background. Either once off, or on a regular schedule.

=== Time API (time) ===

The [[Time API]] takes care of translating and displaying times between users in the site.

=== Testing API (test) ===

The testing API contains the Unit test API ([[PHPUnit]]) and Acceptance test API ([[Acceptance testing]]). Ideally all new code should have unit tests written FIRST.

=== User-related APIs (user) ===

This is a rather informal grouping of miscellaneous [[User-related APIs]] relating to sorting and searching lists of users.

=== Web services API (webservice) ===

The [[Web services API]] allows you to expose particular functions (usually external functions) as web services.

=== Badges API (badges) ===

The [https://docs.moodle.org/dev/OpenBadges_User_Documentation Badges] user documentation (is a temp page until we compile a proper page with all the classes and APIs that allows you to manage particular badges and OpenBadges Backpack).

=== Custom fields API ===

The [[Custom fields API]] allows you to configure and add custom fields for different entities

== Activity module APIs ==

Activity modules are the most important plugin in Moodle. There are several core APIs that service only Activity modules.

=== Activity completion API (completion) ===

The [[Activity completion API]] is to indicate to the system how activities are completed.

=== Advanced grading API (grading) ===

The [[Advanced grading API]] allows you to add more advanced grading interfaces (such as rubrics) that can produce simple grades for the gradebook.

=== Conditional activities API (condition) - deprecated in 2.7 ===

The deprecated [[Conditional activities API]] used to provide conditional access to modules and sections in Moodle 2.6 and below. It has been replaced by the [[Availability API]].

=== Groups API (group) ===

The [[Groups API]] allows you to check the current activity group mode and set the current group.

=== Gradebook API (grade) ===

The [[Gradebook API]] allows you to read and write from the gradebook. It also allows you to provide an interface for detailed grading information.

=== Plagiarism API (plagiarism) ===

The [[Plagiarism API]] allows your activity module to send files and data to external services to have them checked for plagiarism.

=== Question API (question) ===

The [[Question API]] (which can be divided into the Question bank API and the Question engine API), can be used by activities that want to use questions from the question bank.

== See also ==

* [[Plugins]] - plugin types also have their own APIs
* [[Callbacks]] - list of all callbacks in Moodle
* [[Coding style]] - general information about writing PHP code for Moodle

[[ja:コアAPI]]

User-related APIs

2021-03-11T12:45:16Z

Quen:

== Overview ==

This is a collection of miscellaneous APIs that can help with doing things with lists of users. Note that, in many cases, the more specific [[Access API]], [[Groups API]], [[Enrolment API]], etc. may be what you need.

== User field display ==

[[User fields API]] (temp link, updating in progress)

== User fields definition ==

{{Moodle 3.1}}
To guarantee the sanity of the data inserted into Moodle and avoid security bugs, new user fields definition methods have been created for use in Moodle 3.1 onwards. The purpose of these new methods is to create a central point of user fields data validation and guarantee all data inserted into Moodle will be cleaned against the correct parameter type. Another goal of this new API is to create consistency across Moodle core and avoid different parameter validations for the same user fields. For now on, user data must validate against the user field, not using clean_param() directly.

===$propertiescache===
Cached information of each user field and its attributes filled by the fill_properties_cache.

===fill_properties_cache()===
The main method of the user definition is to keep the definition of each user field and its properties. It verifies if the '''core_user::$propertiescache''' is already filled and caches all user fields attributes into this same attribute.
Each field matches the exact field name on the user table. That said, every new field added to the user table should be added to fill_properties_cache $fields array, otherwise it won't be validated or cleaned.
Each field has four possible properties, being choices and default optional:

* '''null''' - Whether the field is NULL or NOT_NULL, it SHOULD NOT be used as form validation, as many fields in the user table have NOT_NULL property but have the default value as (``).
* '''type''' - The expected parameter type (PARAM_*) to be used as validation and sanitizing.
* '''choices''' - A list of accepted values of that field. For example the list of the available countries, timezones, calendar type etc.
* '''default''' - The default value in case the user field didn't pass the validation or cleaned and we must set the default value. For example if the user country is invalid and it is not in the list of choices, set $CFG->country.

===validate()===
A static method to validate user fields, accepts an array or the user object as parameter, validate each parameter individually and can return true if all user data is correct or an array of validation errors. The purpose of this method is to just validate the user data, it won’t do any cleaning of the data.

===clean_data()===
A static method that has the purpose of clean the user data and return the same user array/object. It receives an array with user data or a user object as parameter and it checks if the data is in the list of choices and if the property has a default value and clean the data if the user object doesn’t have a choices property.
It will display a debugging message if one the operations above has problems.

===clean_field()===
A static method to clean a single user field. It has two parameters, the data to be cleaned and its user field. The behaviour of the method is similar to the clean_data. It will do the validations and cleaning and can display a debug message if an error has been found. It returns the cleaned data.

===get_property_type()===
A helper method to get the type of the property. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return its type.

===get_property_null()===
A helper method to get the null property of the user field. It receives the user field name as parameter and if it doesn't exist it throws an exception. If the property has been found, it will return the null value.

===get_property_choices()===
A helper method to get the list of choices of a user field. It receives the user field name as parameter and if it doesn't exist will throw an exception. If the property has been found, it will return the list of accepted values.

===get_property_default()===
A helper method to get the default value of a property. It receives the user field name as parameter and if it doesn't exist or if it doesn't have a default attribute will throw an exception. If the property has been found, it will return its default value.

== User selector ==

The base class <tt>user_selector_base</tt> defined in <tt>user/selector/lib.php</tt>, which you can subclass to make a widget that lets you select users in an AJAX-y way. It is used, for example, on the Add group members page. The best way to learn how to use it is to search the code for other users, and see how they work. The base class also has good PHPdoc comments.

== Sorting lists of users ==

When you fetch a list of users from the database, they should always be sorted consistently, by using the <tt>users_order_by_sql</tt> function to generate the order-by clause. Again, the best way to see how that works is to search the code for existing uses.

== Others ==

''Please add more..''

==See also==

* [[Core APIs]]
* [[Access API]]
* [[Groups API]]
* [[Enrolment API]]

[[Category:API]]

User fields

2021-03-11T12:38:25Z

Quen: /* Getting SQL */

{{Moodle 3.11}}

The user fields API is located in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

== Overview ==

This API is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This API supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC", [], 0, 10);
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can create SQL snippets for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT u.id, u.deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T12:31:12Z

Quen: /* Add or remove arbitrary extra fields */

{{Moodle 3.11}}

The user fields API is located in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

== Overview ==

This API is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This API supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is the basic SQL that does this:

<code sql>
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can write the SQL for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT id, deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T12:30:49Z

Quen: /* Add or remove custom fields to a list */

{{Moodle 3.11}}

The user fields API is located in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

== Overview ==

This API is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This API supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove arbitrary extra fields ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this could be if you know you are going to have that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is the basic SQL that does this:

<code sql>
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can write the SQL for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT id, deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T12:28:38Z

Quen: /* List fields required to display a user's identity */

{{Moodle 3.11}}

The user fields API is located in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

== Overview ==

This API is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This API supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table columns.

Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove custom fields to a list ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this could be if you know you are going to have that field in a database query separately.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is the basic SQL that does this:

<code sql>
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can write the SQL for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT id, deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T12:27:19Z

Quen: /* Custom fields */

{{Moodle 3.11}}

The user fields API is located in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

== Overview ==

This API is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This API supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table.

Because the permission depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove custom fields to a list ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this could be if you know you are going to have that field in a database query separately.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is the basic SQL that does this:

<code sql>
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can write the SQL for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT id, deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T12:26:40Z

Quen:

{{Moodle 3.11}}

The user fields API is located in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

== Overview ==

This API is normally used when displaying lists of users in a table. It has the following main functions.

# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
# Provide lists of fields required for showing user picture or full name.
# Provide SQL that can be used within a query to get that information for users.

== Custom fields ==

This API supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field with shortname frog is prefixed, so it is referred to as <tt>profile_field_frog</tt>.

== Listing fields ==

The following examples describe how you can get a list of user fields for a certain situation.

=== List fields required to display a user picture ===

<code php>
$fields = \core\user_fields::for_userpic()->get_required_fields();
</code>

This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).

These are the fields you need to have in the user object in order to call the <tt>$OUTPUT->user_picture($user)</tt> function.

=== List fields required to display a user's full name ===

<code php>
$fields = \core\user_fields::for_name()->get_required_fields();
</code>

This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).

These are the fields you need to have in the user object in order to call the <tt>fullname($user)</tt> function.

=== List fields required to display a user picture and full name ===

<code php>
$fields = \core\user_fields::for_name()->with_userpic()->get_required_fields();
</code>

If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.

=== List fields required to display a user's identity ===

When displaying a table of users, the name is always included (and sometimes a picture), as above. Other 'identity fields' are configurable using the <tt>showuseridentity</tt> admin setting, and display only to users who have the permission to see them. For example, it could be configured so that email addresses are shown, or user names, or department, or a custom field. These fields usually display in separate table.

Because the permission depends on the location you are looking at, you need to pass a context when getting these fields.

<code php>
$fields = \core\user_fields::for_identity($context)->get_required_fields();
</code>

The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

<code php>
$fields = \core\user_fields::for_identity($context, false)->get_required_fields();
</code>

Now it won't return any custom profile fields (and your code doesn't support them, which is sad).

=== Add or remove custom fields to a list ===

Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

<code php>
$fields = \core\user_fields::for_identity($context)->including('email')->get_required_fields();
</code>

Alternatively you might want to exclude a field - this could be if you know you are going to have that field in a database query separately.

<code php>
$fields = \core\user_fields::for_name()->excluding('firstname')->get_required_fields();
</code>

You can use both including and excluding functions if you want.

== Getting SQL ==

In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is the basic SQL that does this:

<code sql>
SELECT u.id, u.deleted
FROM {user} u
ORDER BY u.lastaccess DESC
</code>

Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.

We can create a user fields object like this:

<code php>
$context = \context_system::instance();
$userfields = \core\user_fields::for_name()->with_identity($context)->excluding('id', 'deleted');
</code>

The user fields object can write the SQL for you like this:

<code php>
$sql = $userfields->get_sql('u');
</code>

This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

<code php>
$result = $DB->get_records_sql("
SELECT id, deleted {$sql->selects}
FROM {user} u
{$sql->joins}
ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
</code>

There are many options to the get_sql function, as well as the user table alias shown. For example, you can:

* Use named parameters instead of ? parameters.
* Add a prefix (e.g.u_) to all field names in the result to ensure they don't clash with other fields in the query.
* Rename the userid field e.g. to 'userid'.
* Turn off the leading comma in the selects list.

This last one might need explaining. By default, the 'selects' list starts with a comma, which means you include it in the query as shown above (without a comma before it). By doing this, it will still work correctly if there are no fields to add (then it returns selects as blank, so there is no 'spare' comma).

== Selective field lists ==

When you have created a user fields object that includes a lot of fields for different purposes, like the one in the above example, you might need to get a list of only some of those fields. The most common use case for this is when deciding on columns to display in a table. In the above example, we don't want a column in the table for every fields in the $userfields object - there doesn't need to be a column for the 'firstnamephonetic' field, for instance. But we do need to know the extra identity fields that are being included, because these should each have a column.

An extra parameter on get_required_fields lets you include only one category of fields from the object:

<code php>
$extracolumns = $userfields->get_required_fields([\core\user_fields::PURPOSE_IDENTITY]);
</code>

== Field names ==

To display those columns you will need a header with a field name. You can get a field name as follows:

<code php>
$header = \core\user_fields::get_display_name($field);
</code>

This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

== Older Moodle versions ==

Prior to Moodle 3.11 the main functions used to carry out the same jobs were called <tt>get_extra_user_fields()</tt>, <tt>get_extra_user_fields_sql()</tt>, <tt>user_picture::fields()</tt>, and <tt>get_all_user_name_fields()</tt>. These all work, but are deprecated, in Moodle 3.11.

User fields

2021-03-11T11:44:38Z

Quen: Created page with "{{Moodle 3.11}} The user fields API is located in the class <code>\core\user_fields</code>. (Document in progress...)"

{{Moodle 3.11}}

The user fields API is located in the class <code>\core\user_fields</code>.

(Document in progress...)

Core APIs

2021-03-11T11:43:48Z

Quen: /* User-related APIs (user) */

Moodle has a number of core APIs that provide tools for Moodle scripts.

They are essential when writing [[Plugins|Moodle plugins]].

==Most-used General APIs==

These APIs are critical and will be used by nearly every Moodle plugin.

=== Access API (access) ===

The [[Access API]] gives you functions so you can determine what the current user is allowed to do, and it allows modules to extend Moodle with new capabilities.

=== Data manipulation API (dml) ===

The [[Data manipulation API]] allows you to read/write to databases in a consistent and safe way.

=== File API (files) ===

The [[File API]] controls the storage of files in connection to various plugins.

=== Form API (form) ===

The [[Form API]] defines and handles user data via web forms.

=== Logging API (log) ===

The [[Events API]] allows you to log events in Moodle, while [[Logging 2]] describes how logs are stored and retrieved.

=== Navigation API (navigation) ===

The [[Navigation API]] allows you to manipulate the navigation tree to add and remove items as you wish.

=== Page API (page) ===

The [[Page API]] is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

=== Output API (output) ===

The [[Output API]] is used to render the HTML for all parts of the page.

=== String API (string) ===

The [[String API]] is how you get language text strings to use in the user interface. It handles any language translations that might be available.

=== Upgrade API (upgrade) ===

The [[Upgrade API]] is how your module installs and upgrades itself, by keeping track of its own version.

=== Moodlelib API (core) ===

The [[Moodlelib API]] is the central library file of miscellaneous general-purpose Moodle functions. Functions can over the handling of request parameters, configs, user preferences, time, login, mnet, plugins, strings and others. There are plenty of defined constants too.

==Other General APIs==

=== Admin settings API (admin) ===

The [[Admin settings]] API deals with providing configuration options for each plugin and Moodle core.

=== Analytics API (analytics) ===

The [[Analytics API]] allow you to create prediction models and generate insights.

=== Availability API (availability) ===

The [[Availability API]] controls access to activities and sections.

=== Backup API (backup) ===

The [[Backup API]] defines exactly how to convert course data into XML for backup purposes, and the [[Restore API]] describes how to convert it back the other way.

=== Cache API (cache) ===

The [[The Moodle Universal Cache (MUC)]] is the structure for storing cache data within Moodle. [[Cache_API]] explains some of what is needed to use a cache in your code.

=== Calendar API (calendar) ===

The [[Calendar API]] allows you to add and modify events in the calendar for user, groups, courses, or the whole site.

=== Check API (check) ===

The [[Check API]] allows you to add security, performance or health checks to your site.

=== Comment API (comment) ===

The [[Comment API]] allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.

=== Competency API (competency) ===

The [[Competency API]] allows you to list and add evidence of competencies to learning plans, learning plan templates, frameworks, courses and activities.

=== Data definition API (ddl) ===

The [[Data definition API]] is what you use to create, change and delete tables and fields in the database during upgrades.

=== Editor API ===

The [[Editor API]] is used to control HTML text editors.

=== Enrolment API (enrol) ===

The [[Enrolment API]] deals with course participants.

=== Events API (event) ===

The [[Events API]] allows to define "events" with payload data to be fired whenever you like, and it also allows you to define handlers to react to these events when they happen. This is the recommended form of inter-plugin communication. This also forms the basis for logging in Moodle.

=== Experience API (xAPI) ===

The Experience API (xAPI) is an e-learning standard that allows learning content and learning systems to speak to each other. The [[Experience API (xAPI)]]
allows any plugin to generate and handle xAPI standard statements.

=== External functions API (external) ===

The [[External functions API]] allows you to create fully parametrised methods that can be accessed by external programs (such as [[Web services]]).

=== Favourites API ===

The [[Favourites API]] allows you to mark items as favourites for a user and manage these favourites. This is often referred to as 'Starred'.

=== Lock API (lock) ===

The [[Lock API]] lets you synchronise processing between multiple requests, even for separate nodes in a cluster.

=== Message API (message) ===

The [[Message API]] lets you post messages to users. They decide how they want to receive them.

=== Media API (media) ===

The [[Media_players#Using_media_players|Media]] API can be used to embed media items such as audio, video, and Flash.

=== My profile API ===

The [[My profile API]] is used to add things to the profile page.

=== OAuth 2 API (oauth2) ===

The [[OAuth 2 API]] is used to provide a common place to configure and manage external systems using OAuth 2.

=== Payment API (payment) ===

The [[Payment API]] deals with payments.

=== Preference API (preference) ===

The [[Preference API]] is a simple way to store and retrieve preferences for individual users.

=== Portfolio API (portfolio) ===

The [[Portfolio API]] allows you to add portfolio interfaces on your pages and allows users to package up data to send to their portfolios.

=== Privacy API (privacy) ===

The [[Privacy API]] allows you to describe the personal data that you store, and provides the means for that data to be discovered, exported, and deleted on a per-user basis.
This allows compliance with regulation such as the General Data Protection Regulation (GDPR) in Europe.

=== Rating API (rating) ===

The [[Rating API]] lets you create AJAX rating interfaces so that users can rate items in your plugin. In an activity module, you may choose to aggregate ratings to form grades.

=== RSS API (rss) ===

The [[RSS API]] allows you to create secure RSS feeds of data in your module.

=== Search API (search) ===

The [[Search API]] allows you to index contents in a search engine and query the search engine for results.

=== Tag API (tag) ===

The [[Tag API]] allows you to store tags (and a tag cloud) to items in your module.

=== Task API (task) ===

The [[Task API]] lets you run jobs in the background. Either once off, or on a regular schedule.

=== Time API (time) ===

The [[Time API]] takes care of translating and displaying times between users in the site.

=== Testing API (test) ===

The testing API contains the Unit test API ([[PHPUnit]]) and Acceptance test API ([[Acceptance testing]]). Ideally all new code should have unit tests written FIRST.

=== User-related APIs (user) ===

This is a rather informal grouping of miscellaneous [[User-related APIs]] relating to sorting and searching lists of users.

=== User fields API ===

The [[User fields API]] is mainly used when displaying tables of data about users. It indicates which extra fields (e.g. email) should be displayed in the current context based on the permissions of the current user. It also provides ways to get the necessary data from a query, and to obtainother generally-useful fields for user names and pictures.

=== Web services API (webservice) ===

The [[Web services API]] allows you to expose particular functions (usually external functions) as web services.

=== Badges API (badges) ===

The [https://docs.moodle.org/dev/OpenBadges_User_Documentation Badges] user documentation (is a temp page until we compile a proper page with all the classes and APIs that allows you to manage particular badges and OpenBadges Backpack).

=== Custom fields API ===

The [[Custom fields API]] allows you to configure and add custom fields for different entities

== Activity module APIs ==

Activity modules are the most important plugin in Moodle. There are several core APIs that service only Activity modules.

=== Activity completion API (completion) ===

The [[Activity completion API]] is to indicate to the system how activities are completed.

=== Advanced grading API (grading) ===

The [[Advanced grading API]] allows you to add more advanced grading interfaces (such as rubrics) that can produce simple grades for the gradebook.

=== Conditional activities API (condition) - deprecated in 2.7 ===

The deprecated [[Conditional activities API]] used to provide conditional access to modules and sections in Moodle 2.6 and below. It has been replaced by the [[Availability API]].

=== Groups API (group) ===

The [[Groups API]] allows you to check the current activity group mode and set the current group.

=== Gradebook API (grade) ===

The [[Gradebook API]] allows you to read and write from the gradebook. It also allows you to provide an interface for detailed grading information.

=== Plagiarism API (plagiarism) ===

The [[Plagiarism API]] allows your activity module to send files and data to external services to have them checked for plagiarism.

=== Question API (question) ===

The [[Question API]] (which can be divided into the Question bank API and the Question engine API), can be used by activities that want to use questions from the question bank.

== See also ==

* [[Plugins]] - plugin types also have their own APIs
* [[Callbacks]] - list of all callbacks in Moodle
* [[Coding style]] - general information about writing PHP code for Moodle

[[ja:コアAPI]]

Message API

2020-11-26T11:54:04Z

Quen: Changing the message send example to show how to actually send a notification from a plugin which is what this page is about...

==What is this document?==

This document describes how to make use of the Moodle Messaging API to send messages to Moodle users.

If you are after a general introduction on using the Moodle Messaging system go to [[:en:Messaging|messaging user documentation]].

If you are looking for details of how the Messaging system's internal structure was implemented, go to [[Messaging 2.0]].

If you are looking for instructions on the implementation of a custom message processor (a component that receives messages sent to a user), go to [[Messaging custom components]].

If you are looking for instructions on sending messages programatically within Moodle then read on...

==Overview==

Moodle components have the ability to send messages to users via the Moodle messaging system. Any type of component, for example a plugin or block, can register as a message producer then send messages to users.

==File locations==

The Message API code is contained within lib/messagelib.php and is automatically included for you during page setup.

==Functions==

message_send() is the primary point of contact for the message API. Call it to send a message to a user. You can find a full description of the arguments that must be supplied at (link to phpdocs). There is also an example below.

==Message popup==
{{Moodle_2.9}}
A Javascript popup can be displayed through a link to invite a user to message another. In order to use this feature, you need to require the Javascript libraries using ''message_messenger_requirejs()'' and create a link with the attributes returned by ''message_messenger_sendmessage_link_params()''. More in the examples.

==Examples==

===How to register as a message producer===

The messages produced by a message provider is defined in the /db/messages.php file of a component. Below is code from the quiz module's messages.php file, shown as an example.
<code php>
defined('MOODLE_INTERNAL') || die();
$messageproviders = array (
// Notify teacher that a student has submitted a quiz attempt
'submission' => array (
'capability' => 'mod/quiz:emailnotifysubmission'
),
// Confirm a student's quiz attempt
'confirmation' => array (
'capability' => 'mod/quiz:emailconfirmsubmission'
)
);
</code>

The quiz can send two kinds of messages, quiz "submission" and "confirmation" notifications. Each message type is only available to users with the appropriate capability. Please note that the capability is checked at the system level context. Users who have this capability will have this message listed in their messaging preferences. You can omit the capability section if your message should be visible for all users. For example forum post notifications are available to all users.

<code php>
$messageproviders = array (
// Ordinary single forum posts
'posts' => array (
)
);
</code>

When displaying your message types in a user's messaging preferences it will use a string from your component's language file called "messageprovider:messagename". For example here are the relevant strings from the quiz's language file.
<code php>
$string['messageprovider:confirmation'] = 'Confirmation of your own quiz submissions';
$string['messageprovider:submission'] = 'Notification of quiz submissions';
</code>

Once your messages.php is complete you need to increase the version number of your component in its version.php. That will cause Moodle to check messages.php looking for new or changed message definitions. Log in as an admin and go to /admin/index.php (the Notifications page) to start the upgrade process.
===Setting defaults===
The default processor can be set using an element of the array
e.g.
<code php>
'mynotification' => [
'defaults' => [
'popup' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF,
'email' => MESSAGE_PERMITTED
],
],
</code>
With that setting email will be permitted but disabled for each user by default. It can be turned on by each user through the preferences/notification preferences options (/message/notificationpreferences.php?userid=X)
The possible values are recorded in the lib.php file of messaging
<code php>
/**
* Define contants for messaging default settings population. For unambiguity of
* plugin developer intentions we use 4-bit value (LSB numbering):
* bit 0 - whether to send message when user is loggedin (MESSAGE_DEFAULT_LOGGEDIN)
* bit 1 - whether to send message when user is loggedoff (MESSAGE_DEFAULT_LOGGEDOFF)
* bit 2..3 - messaging permission (MESSAGE_DISALLOWED|MESSAGE_PERMITTED|MESSAGE_FORCED)
*
* MESSAGE_PERMITTED_MASK contains the mask we use to distinguish permission setting
*/
</code>
Note that if you change the values in message.php and then upgrade the plugin the values will not automatically be changed in the config_plugins table where they are stored.

===How to send a message===
{{Moodle_2.9}}
Here is example code showing you how to actually send a notification message. The example shows the construction of a object with specific properties, which is then passed to the message_send() function that uses the information to send a message.
<code php>
$message = new \core\message\message();
$message->component = 'mod_yourmodule'; // Your plugin's name
$message->name = 'mynotification'; // Your notification name from message.php
$message->userfrom = core_user::get_noreply_user(); // If the message is 'from' a specific user you can set them here
$message->userto = $user;
$message->subject = 'message subject 1';
$message->fullmessage = 'message body';
$message->fullmessageformat = FORMAT_MARKDOWN;
$message->fullmessagehtml = '<p>message body</p>';
$message->smallmessage = 'small message';
$message->notification = 1; // Because this is a notification generated from Moodle, not a user-to-user message
$message->contexturl = (new \moodle_url('/course/'))->out(false); // A relevant URL for the notification
$message->contexturlname = 'Course list'; // Link title explaining where users get to for the contexturl
$content = array('*' => array('header' => ' test ', 'footer' => ' test ')); // Extra content for specific processor
$message->set_additional_content('email', $content);

// You probably don't need attachments but if you do, here is how to add one
$usercontext = context_user::instance($user->id);
$file = new stdClass;
$file->contextid = $usercontext->id;
$file->component = 'user';
$file->filearea = 'private';
$file->itemid = 0;
$file->filepath = '/';
$file->filename = '1.txt';
$file->source = 'test';

$fs = get_file_storage();
$file = $fs->create_file_from_string($file, 'file1 content');
$message->attachment = $file;

// Actually send the message
$messageid = message_send($message);
</code>

Before 2.9 message data used to be a stdClass object as shown below (This formation of a message will no longer work as of Moodle 3.6. Only a message object will be accepted):-

<code php>
$message = new stdClass();
$message->component = 'mod_quiz'; //your component name
$message->name = 'submission'; //this is the message name from messages.php
$message->userfrom = $USER;
$message->userto = $touser;
$message->subject = $subject;
$message->fullmessage = $message;
$message->fullmessageformat = FORMAT_PLAIN;
$message->fullmessagehtml = '';
$message->smallmessage = '';
$message->notification = 1; //this is only set to 0 for personal messages between users
message_send($message);
</code>

===How to set-up the message popup===

Here is example code showing you how to set-up the Javascript popup link.
<code php>
require_once('message/lib.php');
$userid = 2;
$userto = $DB->get_record('user', array('id' => $userid));

message_messenger_requirejs();
$url = new moodle_url('message/index.php', array('id' => $userto->id));
$attributes = message_messenger_sendmessage_link_params($userto);
echo html_writer::link($url, 'Send a message', $attributes);
</code>

==Changes in Moodle 3.5==
{{Moodle_3.5}}

In Moodle 3.5, there were some moderately big changes. The only docs I have been able to find about them are in [https://github.com/moodle/moodle/blob/33a388eff737c049786ee42d7430db549568471c/message/upgrade.txt#L56 upgrade.txt] file. However, that is the details, here is an overview:

The main message_send() API to send a message has not changed, so if yout code is just sending messages, you don't need to do anything.

Similarly, message_output plugins don't need to change, so no worries there.

If you are doing things with messages, then you need to understand how the internals have changed.

The database tables have changed. Messages from Moodle components to a user (e.g. mod_quiz), telling them that something has happened (e.g. an attempt was submitted) have always been 'Notifications'. In the past, this was just a column in the mdl_message table. Now, messages and notifications are stored in completely separate tables. Notifications are in mdl_notifications. The strucutre of this table is very similar to the old mdl_message table which is now not used at all. Messages are in mdl_messages, and related tables, that now exist to support group messaging. Those tables join together like this:

<code sql>
SELECT *

FROM mdl_messages m
JOIN mdl_message_conversations con ON con.id = m.conversationid
JOIN mdl_message_conversation_members mem ON mem.conversationid = con.id
LEFT JOIN mdl_message_user_actions act ON act.userid = mem.userid AND act.messageid = m.id

ORDER BY m.timecreated, m.id, mem.userid, act.id
</code>

==See also==
* [[Core APIs]]

[[Category:API]]
[[Category:Tutorial]]
[[Category:Plugins]]
[[Category:Messaging]]

Running acceptance test

2020-11-04T12:00:18Z

Quen: /* 5. Run Behat tests */

== Short version ==

...or how I got it to work on Ubuntu and some of the problems encountered.

You need a bunch of browsers and terminal windows open to do this.

==== 1. Background ====

# I am using the desktop version of Ubuntu 17.04 so there are no issues about running this software in headless mode. Running in headless mode was not tested.
# Moodle is version 3.3 and is a fully installed and working version using the 'standard' Ubuntu LAMP stack.

==== 2. Set up Selenium ====
First, you should have a look at [[Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium#Working_combinations_of_OS.2BBrowser.2Bselenium|working combinations of OS+Browser+selenium]].

# Download the Selenium Standalone Server from [http://www.seleniumhq.org/download/ http://www.seleniumhq.org/download/]. It's a single JAR file, put it anywhere handy.
# Download the Chrome driver from [https://sites.google.com/a/chromium.org/chromedriver/ https://sites.google.com/a/chromium.org/chromedriver/]. Ensure you have the right version of the Chrome driver - see [[#Trouble_shooting| Trouble shooting]]. (Firefox is currently problematic. See [[Actual_Selenium_with_old_Firefox_47.0.1]] if you need to try to make it work.)
# Unzip the driver (it's a single file) and copy to /usr/local/bin (should work anywhere on the path)
# If not installed already, '<tt>sudo apt install default-jre</tt>'
# Start Selenium - '<tt>java -jar /path/to/your/selenium/server/selenium-server-standalone-N.NN.N.jar -port 4444</tt>'
# check it works, access 'localhost:4444/wd/hub/' in your browser and check you can create a new Chrome session.

If running headless or the above doesn't work ("Selenium server is not running" when running the behat tests). Try the following
# Run '<tt>Xvfb -ac :99 -screen 0 1280x1024x16 &</tt>'
# Then immediately, '<tt>export DISPLAY=:99</tt>'
# The run the Selenium command as above

==== 3. Set up Moodle ====

# Create a new 'dataroot' area for files especially for behat adjusting permissions accordingly.
# If not there already, add Section 11 from config-dist.php to your config.php file and review the settings.
# $CFG->behat_wwwroot needs to point to your Moodle site yet be different from the 'normal' wwwroot (e.g. if you used localhost for wwwroot use 127.0.0.1 for the behat_wwwroot). Whatever you choose, make sure it works.
# $CFG->behat_dataroot should point to the directory you created above
# $CFG->behat_prefix should be fine.
# Set up $CFG->behat_profiles to select Chrome as the browser...

$CFG->behat_profiles = [
'default' => [
'browser' => 'chrome',
'extensions' => [
'Behat\MinkExtension' => [
'selenium2' => [
'browser' => 'chrome',
]
]
]
]
];

==== 4. Configure Behat for Moodle ====

# Run '<tt>php admin/tool/behat/cli/init.php</tt>' (from the root of your Moodle install). This installs all the required software and creates the test version of Moodle.

==== 5. Run Behat tests ====

# Run '<tt>vendor/bin/behat</tt>'. If you don't want to run all the tests add '<tt>--tags="@something"</tt>' where the @something refers to the tags at the top of most feature files. Use comma-separated list like '<tt>@some_thing,@some_thing_else</tt>' to run tests from multiple areas. See upstream documentation on Gherkin filters for advanced syntax and more complex examples.
# After some initial setup dots should start to go by. It's a while before Selenium is first accessed. On the Linux desktop a new Chrome window appears and the testing process 'remote control' starts (hopefully!)
# At the end of each line it shows you the number of steps that have completed so far.
#* If you are doing a full run, then as of November 2020 there are about 63,000 steps, which took around 25 hours to complete on one test machine (when not using the parallel running feature).

== Prerequisite ==
Before initializing acceptance test environment for running behat, you should ensure:
# [[Acceptance_testing#Requirements Meet min. system requirements for running tests]]
# [[Acceptance_testing#Installation Have set min. config variable in config.php for behat]]
# [[Acceptance_testing#Installation Downloaded composer dependencies]]

== Overview ==
Acceptance tests (also known as behat), use [http://www.seleniumhq.org/download/ Selenium server] and can be run as:
# '''Single run:''' In single run, only one behat run is executed. So all features are executed in this single run.
# '''Parallel runs:''' (Since Moodle 3.0) Parallel runs allow dev's to execute multiple behat runs together. This was introduced to get acceptance tests results faster. To achieve this:
#* Features are divided between multiple behat runs
#* Symlinks behatrun{x} (x being the run process number), are created pointing to moodle directory, so site for run 1 is accessible via https://localhost/moodle/behatrun1
#* Process number is included as suffix to $CFG->behat_prefix.
#* Process number is suffixed to $CFG->behat_dataroot.

== Step 1: Initialise acceptance test environment ==
Before running acceptance tests, environment needs to be initialised for acceptance testing.

=== Single run ===
For initialising acceptance tests for single run, above command is sufficient.
<code>
php admin/tool/behat/cli/init.php
</code>

=== Parallel runs ===
For initialising acceptance tests for parallel runs, you can use one of the following options
# '''-j=<number> or --parallel=<number>''' (required) Number of parallel behat run to initialise
# '''-m=<number> or --maxruns=<number>''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun=<number>''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun=<number>''' (optional) Initialise site to run specified run till. Used for running acceptance tests on different vms
# '''-o or --optimize-runs''' (optional) This option will split features with specified tags in all parallel runs, so they are executed first when parallel run gets executed.
# '''-a=<name> or --add-core-features-to-theme=<name>''' (optional) Since Moodle 3.2. Use this option to add all core features to specified themes (comma separated list of themes)
<code>
// Below command will initialise moodle to run 2 parallel tests.
php admin/tool/behat/cli/init.php --parallel=2
</code>

== Step 2: Running acceptance test environment ==
=== Single run ===
Run either of the following commands. For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html
<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml
</code>

You almost always want to limit the number of tests that are run. To run all the tests in one plugin:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml --tags mod_myplugin
</code>

To run all the tests in one .feature file:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature
</code>

To run a single scenario:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature:40
</code>

Here, '40' is the line-number of the feature file where the Scenario starts.

=== Parallel runs ===
For running parallel runs, use following command

php admin/tool/behat/cli/run.php

Following optional options are available for custom run:
# '''--feature''' Only execute specified feature file (Absolute path of feature file).
# '''--suite''' Features for specified theme will be executed.
# '''--replace''' Replace args string with run process number, useful for output and reruns.
# '''--fromrun''' Execute run starting from (Used for parallel runs on different vms)
# '''--torun''' Execute run till (Used for parallel runs on different vms)
# Behat options can be passed for filtering features/scenarios:
#* In case you don't want to run Javascript tests, use the Behat tags option to skip them, '''--tags="~@javascript"'''
#* In case you want to run specific scenario, use the Behat name option to run it, '''--name="Filter user accounts by role and cohort"'''
#* In case you want to run specific feature file, use the Behat feature option to run it, '''--feature="/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature"'''

Example: Initialise and run Behat tests for a custom plugin under a custom theme:

php admin/tool/behat/cli/init.php --parallel=3 --add-core-features-to-theme="mytheme"
php admin/tool/behat/cli/run.php --tags="@tool_myplugin" --suite="mytheme"

=== Common options for running tests ===
==== Tests filters ====
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_file_upload''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_alert''': All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.
* '''@_switch_window''': All the tests that are using the '''I switch to "NAME" window''' step should be tagged as not all browsers manage them properly.
* '''@_switch_iframe''': All the tests that are using the '''I switch to "NAME" iframe''' steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

==== Output formats ====
Since Moodle 3.1 option for output is:
<code>
--format=pretty --out=/path/to/pretty.txt --format=moodle_progress --out=std
</code>
Before Moodle 3.1 option for output was:
<code>
--format='moodle_progress,pretty' --out=',/path/to/pretty.txt'
</code>
Following output formats are supported:
# '''progress''': Prints one character per step.
# '''pretty''': Prints the feature as is.
# '''junit''': Outputs the failures in JUnit compatible files.
# '''moodle_progress''': Prints Moodle branch information and dots for each step.
# '''moodle_list''': List all scenarios.
# '''moodle_stepcount''': List all features with total steps in each feature file. Used for parallel run.
# '''moodle_screenshot''': (since Moodle 3.1) Take screenshot and core dump of each step. With following options you can dump either or both.
## --format-settings '{"formats": "image"}'**: will dump image only
## --format-settings '{"formats": "html"}'**: will dump html only.
## --format-settings '{"formats": "html,image"}'**: will dump both.
## --format-settings '{"formats": "html", "dir_permissions": "0777"}'**
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format 'pretty' ('''-f pretty''') is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.

== Advance usage ==
=== Rerun failed scenarios ===
With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option
# '''Single run:''' --run="absolute_path_to_empty_file" (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)
# '''Parallel run:''' --rerun="absolute_path_to_empty_file_{runprocess}.txt --replace="{runprocess}" ({runprocess} will be replaced with the process number for recording fails in the specific run process).
'''Since Moodle 3.1 --rerun option don't accept any value, as it is handled internally by behat'''

=== Running behat with specified theme (Since Moodle 3.2) ===
You can run behat with any theme installed. To execute behat with specified theme use '''--suite={THEME_NAME}''' option, while running behat. By default the features in theme behat folder will be executed for the suite. But if you want to run all core features with the specific theme then initialise acceptance test with --add-core-features-to-theme={THEME_NAME}, e.g.

<code>
php admin/tool/behat/cli/init.php --add-core-features-to-theme=clean
vendor/bin/behat --suite=clean --tags="@enrol_foobar"

</code>

That is a core theme but it will work with custom theme. No = or quotes needed around the theme name.

Make sure that <tt>$CFG->theme</tt> is '''not set''' in your config.php.

==== Override behat core context for theme suite ====
To override behat step definitions so as to run behat with specified theme, you should create a contexts within '''/theme/{MYTHEME}/tests/behat/''' with prefix behat_theme_{MYTHEME}_ and suffixed with the context being overridden. For example, if you want to override behat_mod_forum context, then you should create a class /theme/{MYTHEME}/tests/behat/mod_forum/behat_theme_{MYTHEME}_behat_mod_forum.php

==== Blacklist behat context or features to run in theme suite ====
To blacklist contexts/ features to be executed by theme suite you should create a /theme/{MYTHEME}/tests/behat/blacklist.json file with following format. Following will not use step_definitions from behat_grade and behat_navigation while running theme suite. Also, scenarios in auth/tests/behat/login.feature and grade/tests/behat/grade_hidden_items.feature won't be executed with theme suite.
<code>
{
"contexts": [
"behat_grade",
"behat_navigation",
],
"features": [
"auth/tests/behat/login.feature",
"grade/tests/behat/grade_hidden_items.feature",
]
}
</code>
==== Override core behat selectors ====
To override behat selectors in specific theme, you should create a class behat_theme_{MYTHEME}_behat_selectors in /theme/{MYTHEME}/tests/behat/behat_theme_{MYTHEME}_behat_selectors.php extending behat_selectors.

=== Use php built in web server ===
You can use php built-in-web server for executing behat runs. To do so:
# Open a command line interface and '''cd /to/your/moodle/dirroot'''
# '''php -S localhost:8000''' (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)
# Update $CFG->behat_wwwroot = localhost:8000; in config.php

=== Define custom options for parallel runs ===
You can set following custom config options for parallel runs via $CFG->behat_parallel_run. It's an array of options where 1st array is for 1st run and so on.
<code>
array (
'dbtype' => 'mysqli',
'dblibrary' => 'native',
'dbhost' => 'localhost',
'dbname' => 'moodletest',
'dbuser' => 'moodle',
'dbpass' => 'moodle',
'behat_prefix' => 'mdl_',
'wd_host' => 'http://127.0.0.1:4444/wd/hub',
'behat_wwwroot' => 'http://127.0.0.1/moodle',
'behat_dataroot' => '/home/example/bht_moodledata'
)
</code>

To set different selenium servers for parallel runs, you can use following. NOTE: Running parallel (headless) runs on different selenium servers avoid random focus failures.
<code>
$CFG->behat_parallel_run = array (
array ('wd_host' => 'http://127.0.0.1:4444/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4445/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4446/wd/hub'),
);
</code>

=== Write new tests and behat methods ===

If you want to write tests for your own integration, you can do so by creating new tests with format .feature. Follow instructions in [[Writing_acceptance_tests|this page]] to write new tests.

It is also possible to add new steps the moodle behat integration. In order to do so, you will have to create a new .php class with the prefix '''behat_'''. Copy the format from '''lib\behat\behat_base.php''', but set your class to extend the behat_base class instead of the MinkExtension. You can define new behat steps by declaring functions with the appropriate heading.

You will not be able to use these steps and features right away. Check [[Running_acceptance_test#New_step_definitions_or_features_are_not_executed|this section]] for instructions on how to update the behat integration.

For further information on how to create new steps definitions, check [[Acceptance testing/Custom acceptance steps]].

=== Running acceptance tests with different browser ===

If you follow the steps above, Behat will run with Chrome.

You can get it to run with other browsers. The basic idea is to expand the $CFG->behat_profiles array in config.php to list more browsers.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>

[[Acceptance_testing/Browsers|More info about alternative browsers]]

=== Start multiple selenium servers ===
From command line Start selenium servers at different ports (say 4444, 4445, 4446 for 3 parallel runs)
<code>
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4444 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4445 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4446
</code>

Alternative way of running three Selenium servers in parallel:

$ printf %d\\n {4444..4446} | xargs -n 1 -P 3 java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port

=== Run tests directly in Chrome, with no Selenium ===

Historically, the tests would talk to a Selenium server, which would then tell the target browser what to do. More and more, the browsers themselves contain such a server and you can talk to them directly, which is faster and easier. Work was done to get this working with Chrome in MDL-58948, but it still needs some further setup to get it working, which is detailed in the bug ticket, and which I'll copy below:

Replace your current behat config with the abve, the api_url is where you'll talk directly to your Chrome browser.
<code>
$CFG->behat_config = [
'default' => [
'extensions' => [
'DMore\ChromeExtension\Behat\ServiceContainer\ChromeExtension' => [],
'Behat\MinkExtension' => [
'browser_name' => 'chrome',
'base_url' => $CFG->behat_wwwroot,
'goutte' => null,
'selenium2' => null,
'sessions' => [
'javascript' => [
'chrome' => [
'api_url' => 'http://localhost:9222'
]
]
]
]
]
],
];
</code>

Use composer to install two more required libraries:
<code>
composer require --dev dmore/behat-chrome-extension
composer require --dev dmore/chrome-mink-driver
</code>

If you try to run the tests it will tell you that Chrome isn't running, in a second tab run the following to start Chrome (or chromium-browser on Ubuntu)

<code>chrome --disable-gpu --headless --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222</code>

This is running headless so you won't see any windows pop up as the tests run, though it runs in the other mode too.

Behat should now run as before, but faster.

==== Run Chrome locally with Behat and Moodle on a remote server ====
If you have Moodle running on a remote (headless) server, but don't want to install a window manager, you can do the following:

1. Go through all the steps from above

2. Establish an SSH SOCKS5 proxy connection to your server:
<code>ssh -D VARIABLE-PORT-A -N -q -C USER@SERVER</code>
3. Forward the port to connect to the DevTools-API of your browser:
<code>ssh -R VARIABLE-PORT-B:localhost:VARIABLE-PORT-B USER@SERVER -N -q -C</code>
4. Tell your local Chrome to use custom settings:
<code>/path/to/Google\ Chrome [--disable-gpu] --remote-debugging-address=0.0.0.0 --remote-debugging-port=VARIABLE-PORT-B --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A --proxy-bypass-list='<-loopback>'</code>

Or, all in one command:
<code>ssh -D VARIABLE-PORT-A -N -q -C -f USER@SERVER && ssh -R VARIABLE-PORT-B:localhost:VARIABLE-PORT-B USER@SERVER -N -q -C -f && /path/to/Google\ Chrome [--disable-gpu] --remote-debugging-address=0.0.0.0 --remote-debugging-port=VARIABLE-PORT-B --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A --proxy-bypass-list='<-loopback>'</code>

Explanation for the SSH settings:
* VARIABLE-PORT-B & VARIABLE-PORT-A : Choose these as you like. Bear in mind that you will need root rights if the port number is 1023 or lower
* -N: Tells SSH not to open an actual command prompt
* -C: Compress all data passed through the tunnel
* -q: Quiet mode. Causes most warning and diagnostic messages to be suppressed
*-R: Open a tunnel binding to localhost on the remote machine, going to localhost on the local machine
* -f: Fork the process into background

Explanation for the Chrome settings:
* --proxy-bypass-list='<-loopback>' : Tells Chrome to send requests to localhost through the tunnel
* --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A : To use the SOCKS5 tunnel we just set up
* --remote-debugging-port=VARIABLE-PORT-B & --remote-debugging-address=0.0.0.0 : To use the SSH tunnel we just set up

=== Using Docker to start selenium server ===
==== What is Docker ====
Docker is a app container, it's a kind of virtual machine, but only for one app, service, so you can download
a docker image and run a selenium server without worry in how to configure selenium in your machine, one for chrome, others for firefox, you either don't need to install the browsers in your machine
To install docker follow this link; https://docs.docker.com/engine/installation/

==== Selenium docker images ====
There is many docker images available, for many browser, the complete list is in https://hub.docker.com/u/selenium/
for moodle you can use standalone version.
You can download specific selenium version too, for example, for firefox, moodle recommend selenium 2.53.1, see: [https://docs.moodle.org/dev/Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium What version do I need?]

so the command will be:
<code>
docker run -d -p4444:4444 selenium/standalone-firefox:2.53.1-beryllium
</code>
to see all available version click in tags. For firefox you can find at: https://hub.docker.com/r/selenium/standalone-firefox/tags/

==== Change config.php file ====
In config.php file you must change the $CFG->behat_wwwroot= to your network card (NIC) ip address, you can't use
localhost , 127.0.0.1, ... or selenium docker server will fail

=== Increasing timeouts ===

You may see errors such as:

<code>
Javascript code and/or AJAX requests are not ready after 10 seconds.
There is a Javascript error or the code is extremely slow.
</code>

Sometimes this indicates a genuine problem with the code, but if you are using a slow computer, it could just mean that the browser was not yet ready. You may find that the test works if you run it again. If you get this error frequently, it might be useful to increase the timeout.

It is possible to increase this timeout by adding a line in your config.php. (Requires Moodle versions 3.5 (from 3.5.6), 3.6 (from 3.6.4), or 3.7+.)

<code>
$CFG->behat_increasetimeout = 2;
</code>

This will increase all the timeouts by a factor of 2; if that isn't sufficient, you could use 3.

Increasing timeouts will make tests run a bit slower (because there are points where Behat waits up to a timeout to make sure something doesn't happen) so don't do this unless you need to.

== NOTE ==
# Start the Selenium server (in case you want to run tests that involves Javascript)
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running 'headless' Firefox and xvfm in a server environment)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''

=== Disable acceptance test environment ===
if you want to prevent access to test environment
<code>
php admin/tool/behat/cli/util.php --disable
</code>
'''Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''

== Trouble shooting ==

=== New step definitions or features are not executed ===
If you are adding new tests or steps definitions update the tests list
<code>
php admin/tool/behat/cli/util.php --enable
</code>
''' For parallel runs, all options for initialising parallel runs are valid '''

=== Tests are failing ===

If you followed all the steps and you receive an unknown weird error probably your browser version is not compatible with the Selenium version you are running. Please refer Working combinations to ensure you have correct [[Acceptance_testing/Browsers#Working_combinations_of_OS.2BBrowser.2Bselenium]] of them to run acceptance test.

=== The tests are failing, and the error message is completely useless ===

For example, it just says "Error writing to database" with no stack trace.

Add -vv command-line option to get very verbose output.

=== Errors during setup (before test are launched) ===
Typical errors are:
* Behat requirement not satisfied: http://127.0.0.1/m/stable_master is not available, ensure you specified correct url and that the server is set up and started.
* Behat is configured but not enabled on this test site.

In order to fix those errors please check that: the behat_dataroot has correct write permissions and that the $CFG->behat* variables are placed before the lib/setup.php include:
require_once(__DIR__ . '/lib/setup.php');

=== Selenium server is not running ===
==== Chrome specific ====

If you are using chrome, you need to ensure that the driver matches the version of the installed chrome browser – which may change on OS updates/upgrades. Moodle or Selenium will not give the appropriate message – see [https://tracker.moodle.org/browse/MDL-67659/ MDL-67659]. One solution is the one suggested in the issue and use Andrew Nicols’ [https://github.com/andrewnicols/chromedriver-wrapper/ Chromedriver Wrapper] which will ensure you have the appropriate driver before running the tests.

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat
* Docker containers for Moodle Developers and Behat: https://github.com/moodlehq/moodle-docker
* Docker environment with Behat preconfigured : https://github.com/tobiga/docker_moodle_environment

== See also ==
* [[Acceptance testing for the mobile app]]

[[Category:Quality Assurance]][[Category:Behat]]

Running acceptance test

2020-11-04T11:59:56Z

Quen:

== Short version ==

...or how I got it to work on Ubuntu and some of the problems encountered.

You need a bunch of browsers and terminal windows open to do this.

==== 1. Background ====

# I am using the desktop version of Ubuntu 17.04 so there are no issues about running this software in headless mode. Running in headless mode was not tested.
# Moodle is version 3.3 and is a fully installed and working version using the 'standard' Ubuntu LAMP stack.

==== 2. Set up Selenium ====
First, you should have a look at [[Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium#Working_combinations_of_OS.2BBrowser.2Bselenium|working combinations of OS+Browser+selenium]].

# Download the Selenium Standalone Server from [http://www.seleniumhq.org/download/ http://www.seleniumhq.org/download/]. It's a single JAR file, put it anywhere handy.
# Download the Chrome driver from [https://sites.google.com/a/chromium.org/chromedriver/ https://sites.google.com/a/chromium.org/chromedriver/]. Ensure you have the right version of the Chrome driver - see [[#Trouble_shooting| Trouble shooting]]. (Firefox is currently problematic. See [[Actual_Selenium_with_old_Firefox_47.0.1]] if you need to try to make it work.)
# Unzip the driver (it's a single file) and copy to /usr/local/bin (should work anywhere on the path)
# If not installed already, '<tt>sudo apt install default-jre</tt>'
# Start Selenium - '<tt>java -jar /path/to/your/selenium/server/selenium-server-standalone-N.NN.N.jar -port 4444</tt>'
# check it works, access 'localhost:4444/wd/hub/' in your browser and check you can create a new Chrome session.

If running headless or the above doesn't work ("Selenium server is not running" when running the behat tests). Try the following
# Run '<tt>Xvfb -ac :99 -screen 0 1280x1024x16 &</tt>'
# Then immediately, '<tt>export DISPLAY=:99</tt>'
# The run the Selenium command as above

==== 3. Set up Moodle ====

# Create a new 'dataroot' area for files especially for behat adjusting permissions accordingly.
# If not there already, add Section 11 from config-dist.php to your config.php file and review the settings.
# $CFG->behat_wwwroot needs to point to your Moodle site yet be different from the 'normal' wwwroot (e.g. if you used localhost for wwwroot use 127.0.0.1 for the behat_wwwroot). Whatever you choose, make sure it works.
# $CFG->behat_dataroot should point to the directory you created above
# $CFG->behat_prefix should be fine.
# Set up $CFG->behat_profiles to select Chrome as the browser...

$CFG->behat_profiles = [
'default' => [
'browser' => 'chrome',
'extensions' => [
'Behat\MinkExtension' => [
'selenium2' => [
'browser' => 'chrome',
]
]
]
]
];

==== 4. Configure Behat for Moodle ====

# Run '<tt>php admin/tool/behat/cli/init.php</tt>' (from the root of your Moodle install). This installs all the required software and creates the test version of Moodle.

==== 5. Run Behat tests ====

# Run '<tt>vendor/bin/behat</tt>'. If you don't want to run all the tests add '<tt>--tags="@something"</tt>' where the @something refers to the tags at the top of most feature files. Use comma-separated list like '<tt>@some_thing,@some_thing_else</tt>' to run tests from multiple areas. See upstream documentation on Gherkin filters for advanced syntax and more complex examples.
# After some initial setup dots should start to go by. It's a while before Selenium is first accessed. On the Linux desktop a new Chrome window appears and the testing process 'remote control' starts (hopefully!)
# At the end of each line it shows you the number of steps that have completed so far.
#* If you are doing a full run, then as of November 2020 there are in total approximately 63,000 steps, which took around 25 hours to complete on one test machine (when not using the parallel running feature).

== Prerequisite ==
Before initializing acceptance test environment for running behat, you should ensure:
# [[Acceptance_testing#Requirements Meet min. system requirements for running tests]]
# [[Acceptance_testing#Installation Have set min. config variable in config.php for behat]]
# [[Acceptance_testing#Installation Downloaded composer dependencies]]

== Overview ==
Acceptance tests (also known as behat), use [http://www.seleniumhq.org/download/ Selenium server] and can be run as:
# '''Single run:''' In single run, only one behat run is executed. So all features are executed in this single run.
# '''Parallel runs:''' (Since Moodle 3.0) Parallel runs allow dev's to execute multiple behat runs together. This was introduced to get acceptance tests results faster. To achieve this:
#* Features are divided between multiple behat runs
#* Symlinks behatrun{x} (x being the run process number), are created pointing to moodle directory, so site for run 1 is accessible via https://localhost/moodle/behatrun1
#* Process number is included as suffix to $CFG->behat_prefix.
#* Process number is suffixed to $CFG->behat_dataroot.

== Step 1: Initialise acceptance test environment ==
Before running acceptance tests, environment needs to be initialised for acceptance testing.

=== Single run ===
For initialising acceptance tests for single run, above command is sufficient.
<code>
php admin/tool/behat/cli/init.php
</code>

=== Parallel runs ===
For initialising acceptance tests for parallel runs, you can use one of the following options
# '''-j=<number> or --parallel=<number>''' (required) Number of parallel behat run to initialise
# '''-m=<number> or --maxruns=<number>''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun=<number>''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun=<number>''' (optional) Initialise site to run specified run till. Used for running acceptance tests on different vms
# '''-o or --optimize-runs''' (optional) This option will split features with specified tags in all parallel runs, so they are executed first when parallel run gets executed.
# '''-a=<name> or --add-core-features-to-theme=<name>''' (optional) Since Moodle 3.2. Use this option to add all core features to specified themes (comma separated list of themes)
<code>
// Below command will initialise moodle to run 2 parallel tests.
php admin/tool/behat/cli/init.php --parallel=2
</code>

== Step 2: Running acceptance test environment ==
=== Single run ===
Run either of the following commands. For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html
<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml
</code>

You almost always want to limit the number of tests that are run. To run all the tests in one plugin:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml --tags mod_myplugin
</code>

To run all the tests in one .feature file:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature
</code>

To run a single scenario:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature:40
</code>

Here, '40' is the line-number of the feature file where the Scenario starts.

=== Parallel runs ===
For running parallel runs, use following command

php admin/tool/behat/cli/run.php

Following optional options are available for custom run:
# '''--feature''' Only execute specified feature file (Absolute path of feature file).
# '''--suite''' Features for specified theme will be executed.
# '''--replace''' Replace args string with run process number, useful for output and reruns.
# '''--fromrun''' Execute run starting from (Used for parallel runs on different vms)
# '''--torun''' Execute run till (Used for parallel runs on different vms)
# Behat options can be passed for filtering features/scenarios:
#* In case you don't want to run Javascript tests, use the Behat tags option to skip them, '''--tags="~@javascript"'''
#* In case you want to run specific scenario, use the Behat name option to run it, '''--name="Filter user accounts by role and cohort"'''
#* In case you want to run specific feature file, use the Behat feature option to run it, '''--feature="/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature"'''

Example: Initialise and run Behat tests for a custom plugin under a custom theme:

php admin/tool/behat/cli/init.php --parallel=3 --add-core-features-to-theme="mytheme"
php admin/tool/behat/cli/run.php --tags="@tool_myplugin" --suite="mytheme"

=== Common options for running tests ===
==== Tests filters ====
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_file_upload''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_alert''': All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.
* '''@_switch_window''': All the tests that are using the '''I switch to "NAME" window''' step should be tagged as not all browsers manage them properly.
* '''@_switch_iframe''': All the tests that are using the '''I switch to "NAME" iframe''' steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

==== Output formats ====
Since Moodle 3.1 option for output is:
<code>
--format=pretty --out=/path/to/pretty.txt --format=moodle_progress --out=std
</code>
Before Moodle 3.1 option for output was:
<code>
--format='moodle_progress,pretty' --out=',/path/to/pretty.txt'
</code>
Following output formats are supported:
# '''progress''': Prints one character per step.
# '''pretty''': Prints the feature as is.
# '''junit''': Outputs the failures in JUnit compatible files.
# '''moodle_progress''': Prints Moodle branch information and dots for each step.
# '''moodle_list''': List all scenarios.
# '''moodle_stepcount''': List all features with total steps in each feature file. Used for parallel run.
# '''moodle_screenshot''': (since Moodle 3.1) Take screenshot and core dump of each step. With following options you can dump either or both.
## --format-settings '{"formats": "image"}'**: will dump image only
## --format-settings '{"formats": "html"}'**: will dump html only.
## --format-settings '{"formats": "html,image"}'**: will dump both.
## --format-settings '{"formats": "html", "dir_permissions": "0777"}'**
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format 'pretty' ('''-f pretty''') is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.

== Advance usage ==
=== Rerun failed scenarios ===
With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option
# '''Single run:''' --run="absolute_path_to_empty_file" (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)
# '''Parallel run:''' --rerun="absolute_path_to_empty_file_{runprocess}.txt --replace="{runprocess}" ({runprocess} will be replaced with the process number for recording fails in the specific run process).
'''Since Moodle 3.1 --rerun option don't accept any value, as it is handled internally by behat'''

=== Running behat with specified theme (Since Moodle 3.2) ===
You can run behat with any theme installed. To execute behat with specified theme use '''--suite={THEME_NAME}''' option, while running behat. By default the features in theme behat folder will be executed for the suite. But if you want to run all core features with the specific theme then initialise acceptance test with --add-core-features-to-theme={THEME_NAME}, e.g.

<code>
php admin/tool/behat/cli/init.php --add-core-features-to-theme=clean
vendor/bin/behat --suite=clean --tags="@enrol_foobar"

</code>

That is a core theme but it will work with custom theme. No = or quotes needed around the theme name.

Make sure that <tt>$CFG->theme</tt> is '''not set''' in your config.php.

==== Override behat core context for theme suite ====
To override behat step definitions so as to run behat with specified theme, you should create a contexts within '''/theme/{MYTHEME}/tests/behat/''' with prefix behat_theme_{MYTHEME}_ and suffixed with the context being overridden. For example, if you want to override behat_mod_forum context, then you should create a class /theme/{MYTHEME}/tests/behat/mod_forum/behat_theme_{MYTHEME}_behat_mod_forum.php

==== Blacklist behat context or features to run in theme suite ====
To blacklist contexts/ features to be executed by theme suite you should create a /theme/{MYTHEME}/tests/behat/blacklist.json file with following format. Following will not use step_definitions from behat_grade and behat_navigation while running theme suite. Also, scenarios in auth/tests/behat/login.feature and grade/tests/behat/grade_hidden_items.feature won't be executed with theme suite.
<code>
{
"contexts": [
"behat_grade",
"behat_navigation",
],
"features": [
"auth/tests/behat/login.feature",
"grade/tests/behat/grade_hidden_items.feature",
]
}
</code>
==== Override core behat selectors ====
To override behat selectors in specific theme, you should create a class behat_theme_{MYTHEME}_behat_selectors in /theme/{MYTHEME}/tests/behat/behat_theme_{MYTHEME}_behat_selectors.php extending behat_selectors.

=== Use php built in web server ===
You can use php built-in-web server for executing behat runs. To do so:
# Open a command line interface and '''cd /to/your/moodle/dirroot'''
# '''php -S localhost:8000''' (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)
# Update $CFG->behat_wwwroot = localhost:8000; in config.php

=== Define custom options for parallel runs ===
You can set following custom config options for parallel runs via $CFG->behat_parallel_run. It's an array of options where 1st array is for 1st run and so on.
<code>
array (
'dbtype' => 'mysqli',
'dblibrary' => 'native',
'dbhost' => 'localhost',
'dbname' => 'moodletest',
'dbuser' => 'moodle',
'dbpass' => 'moodle',
'behat_prefix' => 'mdl_',
'wd_host' => 'http://127.0.0.1:4444/wd/hub',
'behat_wwwroot' => 'http://127.0.0.1/moodle',
'behat_dataroot' => '/home/example/bht_moodledata'
)
</code>

To set different selenium servers for parallel runs, you can use following. NOTE: Running parallel (headless) runs on different selenium servers avoid random focus failures.
<code>
$CFG->behat_parallel_run = array (
array ('wd_host' => 'http://127.0.0.1:4444/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4445/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4446/wd/hub'),
);
</code>

=== Write new tests and behat methods ===

If you want to write tests for your own integration, you can do so by creating new tests with format .feature. Follow instructions in [[Writing_acceptance_tests|this page]] to write new tests.

It is also possible to add new steps the moodle behat integration. In order to do so, you will have to create a new .php class with the prefix '''behat_'''. Copy the format from '''lib\behat\behat_base.php''', but set your class to extend the behat_base class instead of the MinkExtension. You can define new behat steps by declaring functions with the appropriate heading.

You will not be able to use these steps and features right away. Check [[Running_acceptance_test#New_step_definitions_or_features_are_not_executed|this section]] for instructions on how to update the behat integration.

For further information on how to create new steps definitions, check [[Acceptance testing/Custom acceptance steps]].

=== Running acceptance tests with different browser ===

If you follow the steps above, Behat will run with Chrome.

You can get it to run with other browsers. The basic idea is to expand the $CFG->behat_profiles array in config.php to list more browsers.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>

[[Acceptance_testing/Browsers|More info about alternative browsers]]

=== Start multiple selenium servers ===
From command line Start selenium servers at different ports (say 4444, 4445, 4446 for 3 parallel runs)
<code>
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4444 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4445 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4446
</code>

Alternative way of running three Selenium servers in parallel:

$ printf %d\\n {4444..4446} | xargs -n 1 -P 3 java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port

=== Run tests directly in Chrome, with no Selenium ===

Historically, the tests would talk to a Selenium server, which would then tell the target browser what to do. More and more, the browsers themselves contain such a server and you can talk to them directly, which is faster and easier. Work was done to get this working with Chrome in MDL-58948, but it still needs some further setup to get it working, which is detailed in the bug ticket, and which I'll copy below:

Replace your current behat config with the abve, the api_url is where you'll talk directly to your Chrome browser.
<code>
$CFG->behat_config = [
'default' => [
'extensions' => [
'DMore\ChromeExtension\Behat\ServiceContainer\ChromeExtension' => [],
'Behat\MinkExtension' => [
'browser_name' => 'chrome',
'base_url' => $CFG->behat_wwwroot,
'goutte' => null,
'selenium2' => null,
'sessions' => [
'javascript' => [
'chrome' => [
'api_url' => 'http://localhost:9222'
]
]
]
]
]
],
];
</code>

Use composer to install two more required libraries:
<code>
composer require --dev dmore/behat-chrome-extension
composer require --dev dmore/chrome-mink-driver
</code>

If you try to run the tests it will tell you that Chrome isn't running, in a second tab run the following to start Chrome (or chromium-browser on Ubuntu)

<code>chrome --disable-gpu --headless --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222</code>

This is running headless so you won't see any windows pop up as the tests run, though it runs in the other mode too.

Behat should now run as before, but faster.

==== Run Chrome locally with Behat and Moodle on a remote server ====
If you have Moodle running on a remote (headless) server, but don't want to install a window manager, you can do the following:

1. Go through all the steps from above

2. Establish an SSH SOCKS5 proxy connection to your server:
<code>ssh -D VARIABLE-PORT-A -N -q -C USER@SERVER</code>
3. Forward the port to connect to the DevTools-API of your browser:
<code>ssh -R VARIABLE-PORT-B:localhost:VARIABLE-PORT-B USER@SERVER -N -q -C</code>
4. Tell your local Chrome to use custom settings:
<code>/path/to/Google\ Chrome [--disable-gpu] --remote-debugging-address=0.0.0.0 --remote-debugging-port=VARIABLE-PORT-B --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A --proxy-bypass-list='<-loopback>'</code>

Or, all in one command:
<code>ssh -D VARIABLE-PORT-A -N -q -C -f USER@SERVER && ssh -R VARIABLE-PORT-B:localhost:VARIABLE-PORT-B USER@SERVER -N -q -C -f && /path/to/Google\ Chrome [--disable-gpu] --remote-debugging-address=0.0.0.0 --remote-debugging-port=VARIABLE-PORT-B --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A --proxy-bypass-list='<-loopback>'</code>

Explanation for the SSH settings:
* VARIABLE-PORT-B & VARIABLE-PORT-A : Choose these as you like. Bear in mind that you will need root rights if the port number is 1023 or lower
* -N: Tells SSH not to open an actual command prompt
* -C: Compress all data passed through the tunnel
* -q: Quiet mode. Causes most warning and diagnostic messages to be suppressed
*-R: Open a tunnel binding to localhost on the remote machine, going to localhost on the local machine
* -f: Fork the process into background

Explanation for the Chrome settings:
* --proxy-bypass-list='<-loopback>' : Tells Chrome to send requests to localhost through the tunnel
* --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A : To use the SOCKS5 tunnel we just set up
* --remote-debugging-port=VARIABLE-PORT-B & --remote-debugging-address=0.0.0.0 : To use the SSH tunnel we just set up

=== Using Docker to start selenium server ===
==== What is Docker ====
Docker is a app container, it's a kind of virtual machine, but only for one app, service, so you can download
a docker image and run a selenium server without worry in how to configure selenium in your machine, one for chrome, others for firefox, you either don't need to install the browsers in your machine
To install docker follow this link; https://docs.docker.com/engine/installation/

==== Selenium docker images ====
There is many docker images available, for many browser, the complete list is in https://hub.docker.com/u/selenium/
for moodle you can use standalone version.
You can download specific selenium version too, for example, for firefox, moodle recommend selenium 2.53.1, see: [https://docs.moodle.org/dev/Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium What version do I need?]

so the command will be:
<code>
docker run -d -p4444:4444 selenium/standalone-firefox:2.53.1-beryllium
</code>
to see all available version click in tags. For firefox you can find at: https://hub.docker.com/r/selenium/standalone-firefox/tags/

==== Change config.php file ====
In config.php file you must change the $CFG->behat_wwwroot= to your network card (NIC) ip address, you can't use
localhost , 127.0.0.1, ... or selenium docker server will fail

=== Increasing timeouts ===

You may see errors such as:

<code>
Javascript code and/or AJAX requests are not ready after 10 seconds.
There is a Javascript error or the code is extremely slow.
</code>

Sometimes this indicates a genuine problem with the code, but if you are using a slow computer, it could just mean that the browser was not yet ready. You may find that the test works if you run it again. If you get this error frequently, it might be useful to increase the timeout.

It is possible to increase this timeout by adding a line in your config.php. (Requires Moodle versions 3.5 (from 3.5.6), 3.6 (from 3.6.4), or 3.7+.)

<code>
$CFG->behat_increasetimeout = 2;
</code>

This will increase all the timeouts by a factor of 2; if that isn't sufficient, you could use 3.

Increasing timeouts will make tests run a bit slower (because there are points where Behat waits up to a timeout to make sure something doesn't happen) so don't do this unless you need to.

== NOTE ==
# Start the Selenium server (in case you want to run tests that involves Javascript)
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running 'headless' Firefox and xvfm in a server environment)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''

=== Disable acceptance test environment ===
if you want to prevent access to test environment
<code>
php admin/tool/behat/cli/util.php --disable
</code>
'''Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''

== Trouble shooting ==

=== New step definitions or features are not executed ===
If you are adding new tests or steps definitions update the tests list
<code>
php admin/tool/behat/cli/util.php --enable
</code>
''' For parallel runs, all options for initialising parallel runs are valid '''

=== Tests are failing ===

If you followed all the steps and you receive an unknown weird error probably your browser version is not compatible with the Selenium version you are running. Please refer Working combinations to ensure you have correct [[Acceptance_testing/Browsers#Working_combinations_of_OS.2BBrowser.2Bselenium]] of them to run acceptance test.

=== The tests are failing, and the error message is completely useless ===

For example, it just says "Error writing to database" with no stack trace.

Add -vv command-line option to get very verbose output.

=== Errors during setup (before test are launched) ===
Typical errors are:
* Behat requirement not satisfied: http://127.0.0.1/m/stable_master is not available, ensure you specified correct url and that the server is set up and started.
* Behat is configured but not enabled on this test site.

In order to fix those errors please check that: the behat_dataroot has correct write permissions and that the $CFG->behat* variables are placed before the lib/setup.php include:
require_once(__DIR__ . '/lib/setup.php');

=== Selenium server is not running ===
==== Chrome specific ====

If you are using chrome, you need to ensure that the driver matches the version of the installed chrome browser – which may change on OS updates/upgrades. Moodle or Selenium will not give the appropriate message – see [https://tracker.moodle.org/browse/MDL-67659/ MDL-67659]. One solution is the one suggested in the issue and use Andrew Nicols’ [https://github.com/andrewnicols/chromedriver-wrapper/ Chromedriver Wrapper] which will ensure you have the appropriate driver before running the tests.

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat
* Docker containers for Moodle Developers and Behat: https://github.com/moodlehq/moodle-docker
* Docker environment with Behat preconfigured : https://github.com/tobiga/docker_moodle_environment

== See also ==
* [[Acceptance testing for the mobile app]]

[[Category:Quality Assurance]][[Category:Behat]]

Moodle App Plugins Development Guide

2020-06-23T11:18:48Z

Quen: /* Initialization */ Fix punctuation in javascript example, it should be semicolon

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is 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. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. 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 [https://ionicframework.com/docs/components/ 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..

==Types of plugins==

We could classify all the plugins in 3 different types:

===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 your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#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 logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile 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 [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your 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 [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate 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 (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

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

<code 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'],
],
],
];
</code>

;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 method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; 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).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>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 (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: 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 mobile.php list, see “Mobile.php supported options” section below.

===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 classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
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', array('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 = array();
}

// 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);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'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,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* 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.
* JavaScript: Empty, because we don’t need any in this case
* Other data: 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-bind to the template.
* Files: 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 and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- 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 attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<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>
<button ion-button 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 %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button 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 }}
</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>
</code>

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> that 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 <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' 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 this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

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 function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for 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 in offline.

Finally, just before the ion-list 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 to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' 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===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
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', array('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 = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

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 ''coreToLocaleString''). 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 db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code 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'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Alternatively, you can use the Moodle Desktop app, it is based on Chromium so you can enable the "Developer Tools" and inspect the HTML, inject javascript, debug, etc...

Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse 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 [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. 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.
* '''moodlecomponent''' (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 ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.
* '''ismenuhandler''': (optional) Supported from the 3.7.1 version of the app. Set it to true 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.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (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.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''method''' (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.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;
* '''coursepagemethod''': (optional) Supported from the 3.8 version of the app. 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.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class, type. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block. Possible values of ''type'':
** "title": 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).
** "prerendered": Your block will display the content and footer returned by the WebService to get the blocks (e.g. core_block_get_course_blocks), so your block's method will never be called.
** any other value: Your block will immediately call the method specified in mobile.php and it will use the template to render the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

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

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

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 CoreCourseFormatDelegate 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. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate
* CoreFilterDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

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 core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

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 core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. 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).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

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 core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

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:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/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:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (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.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open 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 core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button 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 }}
</button>
</code>

====core-course-download-module-main-file====

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

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button 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 }}
</button>
</code>

====core-navbar-buttons====

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 <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<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>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

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:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (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.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button 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 }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button 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 }}
</button>
</code>

====core-site-plugins-call-ws====

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.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button 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 }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button 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 }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button 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 }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. 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.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (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.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button 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 }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button 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 }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button 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 }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

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.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied. Also, objects or arrays in otherdata will be converted to a JSON encoded string.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<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>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==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 "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init 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 this in the init method (only for Moodle 3.8 and onwards).

<code php>
return [
'disabled' => true
];</code>

If the Moodle version is older than 3.8, then the init method should return this:

<code php>
return [
'javascript' => 'this.HANDLER_DISABLED'
];</code>

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict 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 “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====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 WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' 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 ''myVar'' 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 directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' 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 ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' 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 setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: 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 init 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:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': 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 false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' 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 he wants 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 ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code 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 = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool 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:

<code php>
<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>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' 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 ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

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 groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<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>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA 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:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php 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 ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

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 mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, 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 init 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 init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result;
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

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 module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
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.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======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.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() 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.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
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 getActions() function 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 /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' 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 ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(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());
</code>

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 cmid. 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 'section' parameter for the mobile function 'mobile_document_view':

<code 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);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(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;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code 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;
</code>

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

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<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>
</code>

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

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as 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 ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' 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 ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

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 [[Mobile_support_for_plugins#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 [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

===Implement a module similar to mod_label===

In Moodle 3.8 or higher, if your plugin doesn't support ''FEATURE_NO_VIEW_LINK'' and you don't specify a ''coursepagemethod'' then the module will only display the module description in the course page and it won't be clickable in the app, just like mod_label. 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 ''displaydata'').

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 property ''coursepagemethod'' in the mobile.php. 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 default HTML.

If you don't want your module to be clickable then you just need to remove the ''method'' from mobile.php. With these 2 changes you can have a module that behaves like mod_label 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/blog/navigating-lifecycle-events/ this page].

You can define these functions in your plugin javascript:

<code javascript>
this.ionViewCanLeave = function() {
...
};</code>

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.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select 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, ion-radio, ion-checkbox and ion-select 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 WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== 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 ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<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>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' 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:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

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 WebService that we have created.

The first issue we find is that the WebService 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 ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" 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:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button 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">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

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:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

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 WebService 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 the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (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 [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]]

lib/formslib.php Form Definition

2019-12-10T16:27:50Z

Quen: /* autocomplete */ Added documentation of valuehtmlcallback

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>
===Passing parameters to the Form===

The constructor for ''moodleform'' allows a number of parameters including one (''$customdata'') to permit an array of arbitrary data to be passed to your form.

For example, you can pass the data "$email" and "$username" to the Form's class for use inside (say) the definition.
<code php>
...
$mform_simple = new simplehtml_form( null, array('email'=>$email, 'username'=>$username ) );
...
</code>
(the first parameter is $action, ''null'' will cause the form action to be determined automatically)

Secondly, inside the form definition you can use those parameters to set the default values to some of the form's fields
<code php>
...
$mform->addElement('text', 'email', get_string('email'), 'maxlength="100" size="25" ');
$mform->setType('email', PARAM_NOTAGS);
$mform->addRule('email', get_string('missingemail'), 'required', null, 'server');
// Set default value by using a passed parameter
$mform->setDefault('email',$this->_customdata['email']);
...
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

{{Moodle 2.5}}
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:
<code php>
$mform->setExpanded('foo')
</code>

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== autocomplete ===
{{Moodle 3.1}}
Available since Moodle 3.1

<code php>
$searchareas = \core_search\manager::get_search_areas_list(true);
$areanames = array();
foreach ($searchareas as $areaid => $searcharea) {
$areanames[$areaid] = $searcharea->get_visible_name();
}
$options = array(
'multiple' => true,

'noselectionstring' => get_string('allareas', 'search'),
);
$mform->addElement('autocomplete', 'areaids', get_string('searcharea', 'search'), $areanames, $options);
</code>

The autocomplete element is an advanced form element that supports server-side searching - or simple filtering of a predefined list of options. Some benefits of using this form element are that it handles very large datasets extremely well - it has great accessibility built in - and it gives a good user experience. If you have so much data you need to build pagination into a page - you could probably come up with a better design using this. The simplest way to use it is compatible with the standard 'select' form element. You give it a list of options and some parameters to configure how it behaves. The valid parameters for this simple mode of operation are:
* multiple (boolean - default false) - Allow more than one selected item. The data coming from the form will be an array in this case.

[[image:autocomplete_multiple2.png|center|thumb|alt=autocomplete with multiple option|autocomplete with multiple option.]]

* noselectionstring (string - default <nowiki>''</nowiki>) - The text to display when nothing is selected.
* showsuggestions (boolean - default true) - Do not show the list of suggestions when the user starts typing.
* placeholder (string - default <nowiki>''</nowiki>) - The text to show in the search box when it is empty.
* casesensitive (boolean - default false) - Is the search case sensitive ?
* tags (boolean - default false) - This changes the behaviour so that the user can create new valid entries in the list by typing them and pressing enter.
* ajax (string - default <nowiki>''</nowiki>) - This string is the name of an AMD module that can fetch and format results.
* valuehtmlcallback - For use with the AJAX option, so that it can format the initial value of the form field (available since Moodle 3.5)

More explanation on the 'ajax' option. This should be the name of an AMD module that implements 2 functions:
<code javascript>
/**
* Source of data for Ajax element.
*
* @param {String} selector The selector of the auto complete element.
* @param {String} query The query string.
* @param {Function} callback A callback function receiving an array of results.
* @return {Void}
*/
transport: function(selector, query, callback) ...

/**
* Process the results for auto complete elements.
*
* @param {String} selector The selector of the auto complete element.
* @param {Array} results An array or results.
* @return {Array} New array of results.
*/
processResults: function(selector, results)...

</code>
A good example is here: [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/amd/src/frameworks_datasource.js admin/tool/lp/amd/src/frameworks_datasource.js]

The 'valuehtmlcallback' function is needed when an AJAX-supporting form field has an initial value that needs special rendering, similar to how the AJAX code would render it when the user changes it dynamically. For example, if the field contains user ids and its initial value is '1,2' then you want it to use the rendered HTML display for each value (probably a user's name and picture), not just display those numbers. Here is an example, from /search/classes/output/form/search.php:

<code php>
'valuehtmlcallback' => function($value) {
global $DB, $OUTPUT;
$user = $DB->get_record('user', ['id' => (int)$value], '*', IGNORE_MISSING);
if (!$user || !user_can_view_profile($user)) {
return false;
}
$details = user_get_user_details($user);
return $OUTPUT->render_from_template(
'core_search/form-user-selector-suggestion', $details);
}
</code>

The Mustache template used here is the same as the one used by the AJAX code when the field is changed dynamically.

When using the ajax option in an mform with validation etc - it is recommended to sub-class the php class "MoodleQuickForm_autocomplete" so that you can provide a list of name and
values to populate the form element if the form is re-displayed due to a validation error. An example is [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/classes/form/framework_autocomplete.php admin/tool/lp/classes/form/framework_autocomplete.php].

We have provided several useful subclasses of this form element already that are simple to use (course and tags).

<code php>
// Course example.
// Valid options are:
// 'multiple' - boolean multi select
// 'exclude' - array or int, list of course ids to never show
// 'requiredcapabilities' - array of capabilities. Uses ANY to combine them.
// 'limittoenrolled' - boolean Limits to enrolled courses.
// 'includefrontpage' - boolean Enables the frontpage to be selected.
$options = array('multiple' => true, 'includefrontpage' => true);
$mform->addElement('course', 'mappedcourses', get_string('courses'), $options);

// Tags
// Valid options are:
// 'showstandard' - boolean One of the core_tag_tag constants to say which tags to display
// 'component' - string The component name and itemtype define the tag area
// 'itemtype' - string The component name and itemtype define the tag area
$mform->addElement('tags', 'interests', get_string('interestslist'), array('itemtype' => 'user', 'component' => 'core'));
</code>

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

'''BEWARE:''' Unchecked checkboxes return nothing at all (as if they didn't exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. 'Advcheckbox' eliminates this problem.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with some important improvements:

# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.

=== choosecoursefile ===
{{Moodle 1.9}}
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

'''Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.'''

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== editor ===

This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.

<code php>
$mform->addElement('editor', 'fieldname', get_string('labeltext', 'langfile'));
$mform->setType('fieldname', PARAM_RAW);
</code>

NOTE: It won't work properly without the setType() as shown.

If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].

You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:

<code php>
array(
'subdirs'=>0,
'maxbytes'=>0,
'maxfiles'=>0,
'changeformat'=>0,
'context'=>null,
'noclean'=>0,
'trusttext'=>0,
'enable_filemanagement' => true);
</code>

The option 'enable_filemanagement' will display the file management button on true and remove it on false.

To save the data if you don't care about files:
<code php>
$formdata = $mform->get_data();
$text = $formdata->fieldname['text'];
$format = $formdata->fieldname['format'];
</code>

Note: Because the text editor might be "Atto" (depending on user preferences) and Atto has an "autosave" feature - it requires that the combination of $PAGE->url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If there is no requirement to save the file, you can read the file contents directly into a string as follows...

<code php>
$mform->get_file_content('attachment');
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

These elements are now deprecated. Please use the [[#editor|editor]] field type instead.

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===modvisible===
<pre>
$mform->addElement('modvisible', 'visible', get_string('visible'));
</pre>
This is a custom element for selecting a grade visibility in an activity mod update form.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===
{{Moodle 2.3}}
<code php>
$radioarray=array();
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

You can set an 'onchange' attribute when adding or creating the select element:

$form->addElement('select', 'iselTest', 'Test Select:', $arrayOfOptions, array('onchange' => 'javascript:myFunctionToDoSomething();'));

====multi-select====
<pre>
$select = $mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

=====setSelected=====

To set the default selected item in a select element, you can use the 'setSelected' method. The 'setSelected' can either get a value or an array of values.

<pre>
$options = array(
'ff0000' => 'Red',
'00ff00' => 'Green',
'0000ff' => 'Blue'
);
$select = $mform->addElement('select', 'colors', get_string('colors'), $options);
// This will select the colour blue.
$select->setSelected('0000ff');
</pre>

Or for multiple-selection:
<pre>
$skillsarray = array(
'val1' => 'Skill A',
'val2' => 'Skill B',
'val3' => 'Skill C'
);
$mform->addElement('select', 'md_skills', get_string('skills', 'metadata'), $skillsarray);
$mform->getElement('md_skills')->setMultiple(true);
// This will select the skills A and B.
$mform->getElement('md_skills')->setSelected(array('val1', 'val2'));
</pre>

However you probably don't want to do this. Instead you probably want to use setDefault, or set it using the form's setData method.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===selectwithlink===
<pre>
$options = array();
$mform->addElement('selectwithlink', 'scaleid', get_string('scale'), $options, null,
array('link' => $CFG->wwwroot.'/grade/edit/scale/edit.php?courseid='.$COURSE->id, 'label' => get_string('scalescustomcreate')));
</pre>
select type element with options containing link
===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));
</pre>

This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = $mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = $mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', ' ', false);
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''

<pre>
$this->add_action_buttons();
</pre>

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text input element. (For text labels, use the 'static' element.) Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

====RTL support====
{{Moodle 3.2}}

As of Moodle 3.2, some form elements have been refined to better support right-to-left languages. In RTL, most fields should not have their direction flipped, a URL, a path to a file, a number, ... are always displayed LTR. Input fields and text areas now will best guess whether they should be forced to be displayed in LTR based on the PARAM type associated with it. You can call:
<pre>
$mform->setForceLtr('name', true/false);
</pre>
on some form fields (like 'text') to manually set the value, and for directionality.

====float====
{{Moodle 3.7}}
<pre>
$mform->addElement('float', 'defaultmark', get_string('defaultmark', 'question'), $attributes);
</pre>
Use the float element if you want a text box to get a floating point number. This element automatically supports localised decimal separators. You don't need to use setType with the float element.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

===grading===
<code php>
$mform->addElement('grading', 'advancedgrading', get_string('grade').':', array('gradinginstance' => $gradinginstance));
</code>

Custom element for advanced grading plugins.

When adding the 'grading' element to the form, developer must pass an object of class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be thrown.

===questioncategory===
<code php>
$mform->addElement('questioncategory', 'category', get_string('category', 'question'),
array('contexts'=>$contexts, 'top'=>true, 'currentcat'=>$currentcat, 'nochildrenof'=>$currentcat));
</code>
Creates a drop down element to select a question category.

Options are:
'''contexts''' - (required) context in which question appears
'''currentcat''' - (optional) course category
'''top''' - (optional) if true will put top categories on top
'''nochildrenof''' - (optional) Format categories into an indented list reflecting the tree structure

=== filetypes ===
{{Moodle 3.4}}
Available since Moodle 3.4

<code php>
$mform->addElement('filetypes', 'allowedfiletypes', get_string('allowedfiletypes', 'tool_myplugin'));
</code>

Creates an input element allowing the user to specify file types for the given purpose. The typical scenario is a setting that allows the teacher define a list of allowed file types submitted by students.

The element allows the user to either type the list of filetypes manually, or select the types from the list. Also supported is selecting the whole group of file types - such as "image". The element integrates with the [[Core filetypes]] system so all default types and groups are presented, as well as those [[:en:Working with files#Site administration settings|defined locally by the admin]].

As the list can be types in manually, the form processing code should always normalize it first via the provided utility methods:

<code php>
$formdata = $mform->get_data();
$filetypesutil = new \core_form\filetypes_util();
$allowedfiletypes = $filetypesutil->normalize_file_types($formdata->allowedfiletypes);
</code>

This always returns an array of recognized valid values. The original list can be separated by whitespace, end of lines, commas, colons and semicolons. During the normalization, values are converted to lowercase, empty valies and duplicates are removed. Glob evaluation is not supported.

The normalization should also happen if the previously defined list had been saved to the database and re-read for actual usage. The normalization output value can be directly used as the accepted_types option for the filepicker.

<code php>
$filetypesutil = new \core_form\filetypes_util();
$options['accepted_types'] = $filetypesutil->normalize_file_types($allowedfiletypes);
</code>

By default, user input is validated against the list of known file types and groups. This validation can be disabled via options.

'''Supported options'''

; onlytypes : Allow selection from these file types only; for example ['onlytypes' => ['web_image']].
; allowall : Allow to select 'All file types', defaults to true. Does not apply with onlytypes are set.
; allowunknown : Skip implicit validation against the list of known file types.

Example:

<code php>
$mform->addElement('filetypes', 'doctypes', get_string('doctypes', 'tool_myplugin'), ['onlytypes' => ['document'], 'allowunknown' => true]);
</code>

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');
</pre>

* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems);
</pre>

* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems, null, false);
</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

===Server side and Client side===
In case you use the ''Client side'' validation option, you can mainly check for an empty or not input field. unless you write some ''Client side'' code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.
In case you need a more complex validation checks which relay on Moodle's internal PHP libraries (or other/external PHP libraries) you better use the ''Server side'' validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client's side.

==addHelpButton==

<code php>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</code>

The following parameters are expected:

<code php>
/**
* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in
*/
</code>

# get_string($identifier, $component) // The title of the help page
# get_string("{$identifier}_help", $component) // The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers.
<code php>
$mform->addHelpButton('shuffleanswers', 'shuffleanswers', 'qtype_multichoice');
</code>
and so the language file includes the strings
<code php>
$string['shuffleanswers'] = 'Shuffle the choices?';
$string['shuffleanswers_help'] = 'If enabled,.....';
</code>
You can also add the language string like
<code php>
$string['shuffleanswers_link'] = 'question/shuffleanswers';
</code>
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

<pre>
$mform->addElement('editor', 'desc', get_string('description'));
$mform->setDefault('desc', array('text'=>$defaulttext));
</pre>

Note that when setting the default for an editor element you must use an array to define the default "text" value as shown above.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1')

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq', 'in' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'in' then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control when a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'neq', 42);

The possible choices here are in the dependency manager in lib/form/form.js.
===A tricky case===

You need to take care with disabledIf if you plan to use it with groups of checkboxes.

Let's say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.

To fix ideas:

If the selection in the checkboxes group is:

mycheck_01 == 1
mycheck_02 == 0
mycheck_03 == 0
mycheck_04 == 0
mycheck_05 == 1

the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.

The following code will, apparently, fail:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'neq', '1');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'neq', '1');
</code>

In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element "mycheck_01" and will not apply the corresponding rule.

A working solution for this kind of issue seems to be:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'notchecked');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'notchecked');
</code>
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.

==hideIf==
{{Moodle 3.4}}
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
This uses the same syntax as disabledIf just with hideIf instead.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to contain multi-lang content. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers. PARAM_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==disable_form_change_checker==

By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call

$mform->disable_form_change_checker()

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]
[[Category:Interfaces]]

Moodle App Plugins Development Guide

2019-04-15T09:48:30Z

Quen: /* Moodle plugins with mobile support */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle Mobile Remote add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is 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. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. 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 [https://ionicframework.com/docs/components/ 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..

==Types of plugins==

We could classify all the plugins in 3 different types:

===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 your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#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 logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile 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 [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your 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 [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate 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 (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

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

<code 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'],
],
],
];
</code>

;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 method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; 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).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>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 (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: 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 mobile.php list, see “Mobile.php supported options” section below.

===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 classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
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', array('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 = array();
}

// 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);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'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,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* 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.
* JavaScript: Empty, because we don’t need any in this case
* Other data: 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-bind to the template.
* Files: 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 and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- 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 attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<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>
<button ion-button 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 %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button 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 }}
</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>
</code>

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> that 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 <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' 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 this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

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 function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for 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 in offline.

Finally, just before the ion-list 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 to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' 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===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
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', array('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 = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

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 ''coreToLocaleString''). 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 db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code 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'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse 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 [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. 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.
* '''moodlecomponent''' (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 ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (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.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

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

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats.

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please notice that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

====core-format-text====

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 core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

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 core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. 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).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

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 core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

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:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/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:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (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.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open 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 core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button 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 }}
</button>
</code>

====core-course-download-module-main-file====

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

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button 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 }}
</button>
</code>

====core-navbar-buttons====

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 <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<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>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

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:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (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.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button 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 }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button 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 }}
</button>
</code>

====core-site-plugins-call-ws====

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.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button 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 }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button 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 }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button 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 }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. 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.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (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.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button 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 }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button 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 }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button 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 }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

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.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<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>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==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 "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init 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 an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict 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 “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====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 WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' 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 ''myVar'' 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 directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' 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 ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' 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 setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: 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 init 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:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': 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 false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' 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 he wants 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 ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code 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 = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool 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:

<code php>
<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>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' 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 ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

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 groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<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>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA 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:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php 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 ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

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 mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, 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 init 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 init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

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 module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
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.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======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.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() 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.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
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 getActions() function 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 /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' 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 ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(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());
</code>

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 cmid. 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 'section' parameter for the mobile function 'mobile_document_view':

<code 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);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(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;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code 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;
</code>

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

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<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>
</code>

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

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select 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, ion-radio, ion-checkbox and ion-select 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 WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== 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 ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<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>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' 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:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

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 WebService that we have created.

The first issue we find is that the WebService 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 ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" 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:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button 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">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

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:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

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

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)
[[Category:Mobile]]

Running acceptance test

2019-03-21T13:23:51Z

Quen: /* Advance usage */ Added documentation for the new timeout feature.

== Short version ==

...or how I got it to work on Ubuntu and some of the problems encountered.

You need a bunch of browsers and terminal windows open to do this.

==== 1. Background ====

# I am using the desktop version of Ubuntu 17.04 so there are no issues about running this software in headless mode. Running in headless mode was not tested.
# Moodle is version 3.3 and is a fully installed and working version using the 'standard' Ubuntu LAMP stack.

==== 2. Set up Selenium ====

# Download the Selenium Standalone Server from [http://www.seleniumhq.org/download/ http://www.seleniumhq.org/download/]. It's a single JAR file, put it anywhere handy.
# Download the Chrome driver from [https://sites.google.com/a/chromium.org/chromedriver/ https://sites.google.com/a/chromium.org/chromedriver/] (Forget trying to use Firefox, the latest version is not compatible)
# Unzip the driver (it's a single file) and copy to /usr/local/bin (should work anywhere on the path)
# If not installed already, '<tt>sudo apt install default-jre</tt>'
# Start Selenium - '<tt>java -jar /path/to/your/selenium/server/selenium-server-standalone-N.NN.N.jar -port 4444</tt>'
# check it works, access 'localhost:4444/wd/hub/' in your browser and check you can create a new Chrome session.

If running headless or the above doesn't work ("Selenium server is not running" when running the behat tests). Try the following
# Run '<tt>Xvfb -ac :99 -screen 0 1280x1024x16 &</tt>'
# Then immediately, '<tt>export DISPLAY=:99</tt>'
# The run the Selenium command as above

==== 3. Set up Moodle ====

# Create a new 'dataroot' area for files especially for behat adjusting permissions accordingly.
# If not there already, add Section 11 from config-dist.php to your config.php file and review the settings.
# $CFG->behat_wwwroot needs to point to your Moodle site yet be different from the 'normal' wwwroot (e.g. if you used localhost for wwwroot use 127.0.0.1 for the behat_wwwroot). Whatever you choose, make sure it works.
# $CFG->behat_dataroot should point to the directory you created above
# $CFG->behat_prefix should be fine.
# Set up $CFG->behat_profiles to select Chrome as the browser...

$CFG->behat_profiles = [
'default' => [
'browser' => 'chrome',
'extensions' => [
'Behat\MinkExtension' => [
'selenium2' => [
'browser' => 'chrome',
]
]
]
]
];

==== 4. Configure Behat for Moodle ====

# Run '<tt>php admin/tool/behat/cli/init.php</tt>' (from the root of your Moodle install). This installs all the required software and creates the test version of Moodle.

==== 5. Run Behat tests ====

# Run '<tt>vendor/bin/behat</tt>'. If you don't want to run all the tests add '<tt>--tags="@something"</tt>' where the @something refers to the tags at the top of most feature files. Use comma-separated list like '<tt>@some_thing,@some_thing_else</tt>' to run tests from multiple areas. See upstream documentation on Gherkin filters for advanced syntax and more complex examples.
# After some initial setup dots should start to go by. It's a while before Selenium is first accessed. On the Linux desktop a new Chrome window appears and the testing process 'remote control' starts (hopefully!)

== Prerequisite ==
Before initializing acceptance test environment for running behat, you should ensure:
# [[Acceptance_testing#Requirements Meet min. system requirements for running tests]]
# [[Acceptance_testing#Installation Have set min. config variable in config.php for behat]]
# [[Acceptance_testing#Installation Downloaded composer dependencies]]

== Overview ==
Acceptance tests (also known as behat), use [http://www.seleniumhq.org/download/ Selenium server] and can be run as:
# '''Single run:''' In single run, only one behat run is executed. So all features are executed in this single run.
# '''Parallel runs:''' (Since Moodle 3.0) Parallel runs allow dev's to execute multiple behat runs together. This was introduced to get acceptance tests results faster. To achieve this:
#* Features are divided between multiple behat runs
#* Symlinks behatrun{x} (x being the run process number), are created pointing to moodle directory, so site for run 1 is accessible via https://localhost/moodle/behatrun1
#* Process number is included as suffix to $CFG->behat_prefix.
#* Process number is suffixed to $CFG->behat_dataroot.

== Step 1: Initialise acceptance test environment ==
Before running acceptance tests, environment needs to be initialised for acceptance testing.

=== Single run ===
For initialising acceptance tests for single run, above command is sufficient.
<code>
php admin/tool/behat/cli/init.php
</code>

=== Parallel runs ===
For initialising acceptance tests for parallel runs, you can use one of the following options
# '''-j or --parallel''' (required) Number of parallel behat run to initialise
# '''-m or --maxruns''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun''' (optional) Initialise site to run specified run till. Used for running acceptance tests on different vms
# '''-o or --optimize-runs''' (optional) This option will split features with specified tags in all parallel runs, so they are executed first when parallel run gets executed.
# '''-a or --add-core-features-to-theme''' (optional) Since Moodle 3.2. Use this option to add all core features to specified themes (comma separated list of themes)
<code>
// Below command will initialise moodle to run 2 parallel tests.
php admin/tool/behat/cli/init.php --parallel=2
</code>

== Step 2: Running acceptance test environment ==
=== Single run ===
Run either of the following commands. For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html
<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml
</code>

=== Parallel runs ===
For running parallel runs, use following command
<code>
php admin/tool/behat/cli/run.php
</code>
Following optional options are available for custom run:
# '''--feature''' Only execute specified feature file (Absolute path of feature file).
# '''--suite''' Features for specified theme will be executed.
# '''--replace''' Replace args string with run process number, useful for output and reruns.
# '''--fromrun''' Execute run starting from (Used for parallel runs on different vms)
# '''--torun''' Execute run till (Used for parallel runs on different vms)
# '''-a or --add-core-features-to-theme''' (optional) Since Moodle 3.2. Use this option to add all core features to specified theme's (comma separated list)
# Behat options can be passed for filtering features/scenarios:
#* In case you don't want to run Javascript tests, use the Behat tags option to skip them, '''--tags="~@javascript"'''
#* In case you want to run specific scenario, use the Behat name option to run it, '''--name="Filter user accounts by role and cohort"'''
#* In case you want to run specific feature file, use the Behat feature option to run it, '''--feature="/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature"'''

=== Common options for running tests ===
==== Tests filters ====
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_file_upload''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_alert''': All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.
* '''@_switch_window''': All the tests that are using the '''I switch to "NAME" window''' step should be tagged as not all browsers manage them properly.
* '''@_switch_iframe''': All the tests that are using the '''I switch to "NAME" window''' steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

==== Output formats ====
Since Moodle 3.1 option for output is:
<code>
--format=pretty --out=/path/to/pretty.txt --format=moodle_progress --out=std
</code>
Before Moodle 3.1 option for output was:
<code>
--format='moodle_progress,pretty' --out=',/path/to/pretty.txt'
</code>
Following output formats are supported:
# '''progress''': Prints one character per step.
# '''pretty''': Prints the feature as is.
# '''junit''': Outputs the failures in JUnit compatible files.
# '''moodle_progress''': Prints Moodle branch information and dots for each step.
# '''moodle_list''': List all scenarios.
# '''moodle_stepcount''': List all features with total steps in each feature file. Used for parallel run.
# '''moodle_screenshot''': (since Moodle 3.1) Take screenshot and core dump of each step. With following options you can dump either or both.
## --format-settings '{"formats": "image"}'**: will dump image only
## --format-settings '{"formats": "html"}'**: will dump html only.
## --format-settings '{"formats": "html,image"}'**: will dump both.
## --format-settings '{"formats": "html", "dir_permissions": "0777"}'**
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format 'pretty' ('''-f pretty''') is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.

== Advance usage ==
=== Rerun failed scenarios ===
With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option
# '''Single run:''' --run="absolute_path_to_empty_file" (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)
# '''Parallel run:''' --rerun="absolute_path_to_empty_file_{runprocess}.txt --replace="{runprocess}" ({runprocess} will be replaced with the process number for recording fails in the specific run process).
'''Since Moodle 3.1 --rerun option don't accept any value, as it is handled internally by behat'''

=== Running behat with specified theme (Since Moodle 3.2) ===
You can run behat with any theme installed. To execute behat with specified theme use '''--suite={THEME_NAME}''' option, while running behat. By default the features in theme behat folder will be executed for the suite. But if you want to run all core features with the specific theme then initialise acceptance test with -a option. For example, '''-a {THEME_NAME}''' e.g.

<code>
php admin/tool/behat/cli/init.php -a clean
vendor/bin/behat --suite=clean --tags="@enrol_foobar"

</code>

That is a core theme but it will work with custom theme. No = or quotes needed around the theme name.

Make sure that <tt>$CFG->theme</tt> is '''not set''' in your config.php.

==== Override behat core context for theme suite ====
To override behat step definitions so as to run behat with specified theme, you should create a contexts within '''/theme/{MYTHEME}/tests/behat/''' with prefix behat_theme_{MYTHEME}_ and suffixed with the context being overridden. For example, if you want to override behat_mod_forum context, then you should create a class /theme/{MYTHEME}/tests/behat/mod_forum/behat_theme_{MYTHEME}_behat_mod_forum.php

==== Blacklist behat context or features to run in theme suite ====
To blacklist contexts/ features to be executed by theme suite you should create a /theme/{MYTHEME}/tests/behat/blacklist.json file with following format. Following will not use step_definitions from behat_grade and behat_navigation while running theme suite. Also, scenarios in auth/tests/behat/login.feature and grade/tests/behat/grade_hidden_items.feature won't be executed with theme suite.
<code>
{
"contexts": [
"behat_grade",
"behat_navigation",
],
"features": [
"auth/tests/behat/login.feature",
"grade/tests/behat/grade_hidden_items.feature",
]
}
</code>
==== Override core behat selectors ====
To override behat selectors in specific theme, you should create a class behat_theme_{MYTHEME}_behat_selectors in /theme/{MYTHEME}/tests/behat/behat_theme_{MYTHEME}_behat_selectors.php extending behat_selectors.

=== Use php built in web server ===
You can use php built-in-web server for executing behat runs. To do so:
# Open a command line interface and '''cd /to/your/moodle/dirroot'''
# '''php -S localhost:8000''' (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)
# Update $CFG->behat_wwwroot = localhost:8000; in config.php

=== Define custom options for parallel runs ===
You can set following custom config options for parallel runs via $CFG->behat_parallel_run. It's an array of options where 1st array is for 1st run and so on.
<code>
array (
'dbtype' => 'mysqli',
'dblibrary' => 'native',
'dbhost' => 'localhost',
'dbname' => 'moodletest',
'dbuser' => 'moodle',
'dbpass' => 'moodle',
'behat_prefix' => 'mdl_',
'wd_host' => 'http://127.0.0.1:4444/wd/hub',
'behat_wwwroot' => 'http://127.0.0.1/moodle',
'behat_dataroot' => '/home/example/bht_moodledata'
)
</code>

To set different selenium servers for parallel runs, you can use following. NOTE: Running parallel (headless) runs on different selenium servers avoid random focus failures.
<code>
$CFG->behat_parallel_run = array (
array ('wd_host' => 'http://127.0.0.1:4444/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4445/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4446/wd/hub'),
);
</code>

=== Write new tests and behat methods ===

If you want to write tests for your own integration, you can do so by creating new tests with format .feature. Follow instructions in [[Writing_acceptance_tests|this page]] to write new tests.

It is also possible to add new steps the moodle behat integration. In order to do so, you will have to create a new .php class with the prefix '''behat_'''. Copy the format from '''lib\behat\behat_base.php''', but set your class to extend the behat_base class instead of the MinkExtension. You can define new behat steps by declaring functions with the appropriate heading.

You will not be able to use these steps and features right away. Check [[Running_acceptance_test#New_step_definitions_or_features_are_not_executed|this section]] for instructions on how to update the behat integration.

For further information on how to create new steps definitions, check [[Acceptance testing/Custom acceptance steps]].

=== Running acceptance tests with different browser ===
By default behat will run with Firefox browser through Selenium. By adding the following code to your config.php you can change the selected browser that is run when behat is invoked. You will need to run php admin/tool/behat/cli/init.php for changes to take effect. Then use --profile='chrome'.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>
[[Acceptance_testing/Browsers|More info about alternative browsers]]

=== Start multiple selenium servers ===
From command line Start selenium servers at different ports (say 4444, 4445, 4446 for 3 parallel runs)
<code>
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4444 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4445 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4446
</code>

Alternative way of running three Selenium servers in parallel:

$ printf %d\\n {4444..4446} | xargs -n 1 -P 3 java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port

=== Using Docker to start selenium server ===
==== What is Docker ====
Docker is a app container, it's a kind of virtual machine, but only for one app, service, so you can download
a docker image and run a selenium server without worry in how to configure selenium in your machine, one for chrome, others for firefox, you either don't need to install the browsers in your machine
To install docker follow this link; https://docs.docker.com/engine/installation/

==== Selenium docker images ====
There is many docker images available, for many browser, the complete list is in https://hub.docker.com/u/selenium/
for moodle you can use standalone version.
You can download specific selenium version too, for example, for firefox, moodle recommend selenium 2.53.1, see: [https://docs.moodle.org/dev/Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium What version do I need?]

so the command will be:
<code>
docker run -d -p4444:4444 selenium/standalone-firefox:2.53.1-beryllium
</code>
to see all available version click in tags. For firefox you can find at: https://hub.docker.com/r/selenium/standalone-firefox/tags/

==== Change config.php file ====
In config.php file you must change the $CFG->behat_wwwroot= to your network card (NIC) ip address, you can't use
localhost , 127.0.0.1, ... or selenium docker server will fail

=== Increasing timeouts ===

You may see errors such as:

<code>
Javascript code and/or AJAX requests are not ready after 10 seconds.
There is a Javascript error or the code is extremely slow.
</code>

Sometimes this indicates a genuine problem with the code, but if you are using a slow computer, it could just mean that the browser was not yet ready. You may find that the test works if you run it again. If you get this error frequently, it might be useful to increase the timeout.

It is possible to increase this timeout by adding a line in your config.php. (Requires Moodle versions 3.5 (from 3.5.6), 3.6 (from 3.6.4), or 3.7+.)

<code>
$CFG->behat_increasetimeout = 2;
</code>

This will increase all the timeouts by a factor of 2; if that isn't sufficient, you could use 3.

Increasing timeouts will make tests run a bit slower (because there are points where Behat waits up to a timeout to make sure something doesn't happen) so don't do this unless you need to.

== NOTE ==
# Start the Selenium server (in case you want to run tests that involves Javascript)
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running 'headless' Firefox and xvfm in a server environment)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''

=== Trouble shooting ===
=== New step definitions or features are not executed ===
If you are adding new tests or steps definitions update the tests list
<code>
php admin/tool/behat/cli/util.php --enable
</code>
''' For parallel runs, all options for initialising parallel runs are valid '''

=== Tests are failing ===
If you followed all the steps and you receive an unknown weird error probably your system's Firefox version is not compatible with the Selenium version you are running. Please refer Working combinations to ensure you have correct [[Acceptance_testing/Browsers#Working_combinations_of_OS.2BBrowser.2Bselenium]] of them to run acceptance test.

=== Disable acceptance test environment ===
if you want to prevent access to test environment
<code>
php admin/tool/behat/cli/util.php --disable
</code>
'''Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat
* Docker containers for Moodle Developers and Behat: https://github.com/moodlehq/moodle-docker
* Docker environment with Behat preconfigured : https://github.com/tobiga/docker_moodle_environment

[[Category:Quality Assurance]]

Acceptance testing/Browsers/Working combinations of OS+Browser+selenium

2019-03-14T16:03:23Z

Quen: /* Moodle 3.4 and up */

= Working combinations of OS+Browser+selenium =
As OS, Browsers and Selenium keeps updating, some combination might fail on different Moodle releases.

Following combinations have been tested at the time of release of Moodle version and will be supported for that combination.

== Moodle 3.4 and up ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|Notes
|-
|style="white-space: nowrap;"|Linux - Debian Stretch
|style="white-space: nowrap;"|Firefox 47.0.1
| [https://selenium-release.storage.googleapis.com/3.141/selenium-server-standalone-3.141.59.jar 3.141.59]
| N/A
| N/A
| Requires special behat config (to be added soon)
|-
| Linux - Debian Stretch
| Chrome 66
| [https://selenium-release.storage.googleapis.com/3.11/selenium-server-standalone-3.11.0.jar 3.11.0]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.38/ 2.38]
| N/A
| Any other valid combination of browser, selenium and chromedriver should work ok, normally. Here there is a [https://github.com/SeleniumHQ/docker-selenium/releases good list] of them, as reference.
|-
| MacOS X
| Firefox 47.0.1
| [https://selenium-release.storage.googleapis.com/3.141/selenium-server-standalone-3.141.59.jar 3.141.59]
| N/A
| N/A
| Requires special behat config (to be added soon)
|-
| MacOS X
| Chrome 72
| [https://selenium-release.storage.googleapis.com/3.141/selenium-server-standalone-3.141.59.jar 3.141.59]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.46/ 2.46]
| N/A
| Any other valid combination of browser, selenium and chromedriver should work ok normally. Here there is a [https://github.com/SeleniumHQ/docker-selenium/releases good list] of them, as reference.
|-
| colspan="6"|General note: Many of the combinations below, for Moodle 3.1 and up, should continue working acceptably well for Moodle 3.4 and up. Just the ones above are actively being used now (CI infrastructure, developers...), hence, verified to be running ok. Feel free to add any other working combination!
|-
| Windows
| Chrome 72
| [https://selenium-release.storage.googleapis.com/3.141/selenium-server-standalone-3.141.59.jar 3.141.59]
| [https://chromedriver.storage.googleapis.com/index.html?path=72.0.3626.69/ 72.0.3626.69]
| N/A
| Any other valid combination of browser, selenium and chromedriver should work ok normally. Here there is a [https://github.com/SeleniumHQ/docker-selenium/releases good list] of them, as reference.
|}

== Moodle 3.2 and 3.3 ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
| Linux - Ubuntu 16.04
| Firefox 47.0.1
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]
| N/A
| N/A
|-
|Linux - Ubuntu 16.04
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F403380%2Fchrome-linux.zip?generation=1467337264475000&alt=media Chrome 53.0]
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]
| N/A
|-
| Linux - Ubuntu 16.04
| Phantomjs 2.1.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Chrome v53.0
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]
| N/A
|-
| MacOS X
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| MacOS X
| [http://www.slimjet.com/chrome/google-chrome-old-version.php Chrome v53.0]
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]
| N/A

|}

== Moodle 3.1 ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
| Linux - Ubuntu 16.04
| [https://download.mozilla.org/?product=firefox-47.0.1-SSL&os=linux64&lang=en-GB Firefox 47.0.1]
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]
| N/A
| N/A
|-
|Linux - Ubuntu 16.04
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&alt=media Chrome 51.0]
| 2.53.1
| 2.22
| N/A
|-
| Linux - Ubuntu 16.04
| Phantomjs 2.1.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Chrome v51.0
| 2.53.1
| 2.22
| N/A
|-
| MacOS X
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| MacOS X
| Chrome v51.0
| 2.53.1
| 2.22
| N/A
|-
| MacOS X
| PhantomJS 2.1.1
| 2.53.1
| N/A
| N/A
|}

== Moodle 3.0 and lower ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
|Linux - Ubuntu 14.10
|Firefox 42.0
|2.47.1
| N/A
| N/A
|-
|Linux - Ubuntu 14.10
|Chrome 46.0
|2.47.1
| 2.19.346067
| N/A
|-
|Linux - Ubuntu 14.10
|Phantomjs 2.0.0
|2.47.1
| N/A
| N/A
|-
|Windows 7/10
|Firefox 41.0
|2.47.1
| N/A
| N/A
|-
|Windows 7/10
|Chrome 47.0
|2.47.1
| 2.20
| N/A
|-
|MacOS X
|Firefox 41.0
|2.47.1
| N/A
| N/A
|-
|MacOS X
|Chrome 46.0
|2.47.1
| 2.20
| N/A
|-
|MacOS X
|Chrome 48.0
|2.51.0
| 2.21
| N/A
|-
|MacOS X
|PhantomJS - 2.0.0 & 2.1.1
|2.48.2
| N/A
| N/A
|}

[[Category:Behat]]

Moodle App Plugins Development Guide

2019-02-14T15:33:43Z

Quen: /* Testing and debugging */ Added a note to remind everyone to turn on display debug messages

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle Mobile Remote add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to suport plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is 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. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. 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 [https://ionicframework.com/docs/components/ 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..

==Types of plugins==

We could classify all the plugins in 3 different types:

===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 your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#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 logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile 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 [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your 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 [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate 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 (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

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

<code 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'],
],
],
];
</code>

;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 method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; 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).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; 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. 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.

===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 classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
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', array('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 = array();
}

// 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);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'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,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* 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.
* JavaScript: Empty, because we don’t need any in this case
* Other data: 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-bind to the template.
* Files: 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 and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- 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 attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<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>
<button ion-button 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 %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button 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 }}
</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>
</code>

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> that 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 <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' 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 this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

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 function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for 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 in offline.

Finally, just before the ion-list 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 to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' 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===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
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', array('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 = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

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 ''coreToLocaleString''). 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 db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code 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'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse 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 [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. 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.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (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.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

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

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats.

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please notice that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

====core-format-text====

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 core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

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 core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional. 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).
* '''inApp''' (boolean): Optional. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional. If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

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 core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

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:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/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:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (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.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open 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 core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button 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 }}
</button>
</code>

====core-course-download-module-main-file====

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

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button 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 }}
</button>
</code>

====core-navbar-buttons====

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 <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<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>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

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:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (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.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button 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 }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button 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 }}
</button>
</code>

====core-site-plugins-call-ws====

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.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button 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 }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button 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 }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button 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 }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. 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.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (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.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button 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 }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button 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 }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button 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 }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

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.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<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>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==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 "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init 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 an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict 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 “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====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 WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' 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 ''myVar'' 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 directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' 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 ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' 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 setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: 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 init 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:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': 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 false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' 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 he wants 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 ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code 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 = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool 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:

<code php>
<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>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' 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 ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

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 groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<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>
</code>

===Initialization===

All handlers can specify a “''init''” method in the mobile.php 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 ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

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 mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, 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 init 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 init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

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 module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
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.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======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.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() 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.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
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 getActions() function 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 /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' 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 ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mmaModCertificate";
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(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());
</code>

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 cmid. 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 'section' parameter for the mobile function 'mobile_document_view':

<code 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);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(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;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the ''CoreUserProfileFieldDelegate'' supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code 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;
</code>

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select 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, ion-radio, ion-checkbox and ion-select 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 WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== 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 ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<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>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' 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:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

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 WebService that we have created.

The first issue we find is that the WebService 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 ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" 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:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button 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">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

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:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

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

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)
[[Category:Mobile]]

Acceptance testing for the Moodle App

2019-02-13T10:44:05Z

Quen:

From Moodle 3.7 it is possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment. There are two ways to do this: you can either set up your own environment manually (which will be useful if you intend to submit changes or bugfixes to the core app), or you can use Docker to set up a virtual environment.

However you set up the environment, if you update the app, you must re-run Behat init on the corresponding Moodle installation so that it knows about the newer app version.

==== Setting up the environment yourself ====

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.

==== Setting up the environment using Docker ====

(For this to work, you must have a Docker installation and know roughly how to use it.)

You can run the app using a Docker image provided by Moodle HQ, with commands like these:

* Specific version 3.6.1

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.1

* Latest stable version:

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest

* Nightly build of the next release

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing.

If you are using a local installation of the app, and want Behat to automatically run the app for you, then put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself before running any Behat tests, and also kill it yourself once you are finished with it.

If you have installed the development environment locally, you can launch it using <tt>ionic serve -b</tt>. After launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

If you run it using Docker, it will automatically start up and you will see similar output.

However you launched it, to use it in Behat, add this line to the Moodle config.php (instead of the behat_ionic_dirroot line above):

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

When you run Behat init, the system needs to know which version of the app you are running. This is used in order to select tests that only work on certain versions of the app (see below).

* If you specify behat_ionic_dirroot, files in this location will be used to determine the app version. (If you also specify behat_ionic_wwwroot, this will not be used to determine the app version, but you should ensure that the version of the running app is the same as the version of the code in behat_ionic_dirroot.)
* If you only specify behat_ionic_wwwroot, the version number will be taken from the running app, so you must ensure the app is running when you run the Behat init command, not only when you start tests. You will get an error if it isn't. (This version detection only works with app version 3.6.1 and above; for older versions you must specify behat_ionic_dirroot.)

The detected version number will be displayed in the output from the init command:

$ php admin/tool/behat/cli/init.php
You are already using composer version 1.8.4 (stable channel).
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
Nothing to install or update
Generating autoload files
Behat test environment already installed
'''Configured app tests for version 3.6.1'''
2.5 behat profile detected, automatically converted to current 3.x format
Acceptance tests environment enabled on http://localhost/core-moodle-github, to run the tests use:
vendor/bin/behat --config C:/mylocation/behat/behat.yml

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

After adding a test with one of these tags (or changing the app version used for testing), make sure you re-run Behat init; it is the init step that decides which tests to include.

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-12T13:49:00Z

Quen: /* Behat init */ Added version number detection info

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment. There are two ways to do this: you can either set up your own environment manually (which will be useful if you intend to submit changes or bugfixes to the core app), or you can use Docker to set up a virtual environment.

However you set up the environment, if you update the app, you must re-run Behat init on the corresponding Moodle installation so that it knows about the newer app version.

==== Setting up the environment yourself ====

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.

==== Setting up the environment using Docker ====

(For this to work, you must have a Docker installation and know roughly how to use it.)

You can run the app using a Docker image provided by Moodle HQ, with commands like these:

* Specific version 3.6.1

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.1

* Latest stable version:

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest

* Nightly build of the next release

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing.

If you are using a local installation of the app, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself before running any Behat tests, and also kill it yourself once you are finished with it.

If you have installed the development environment locally, you can launch it using <tt>ionic serve -b</tt>. After launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

If you run it using Docker, it will automatically start up and you will see similar output.

However you launched it, to use it in Behat, add this line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

When you run Behat init, the system needs to know which version of the app you are running. This is used in order to select tests that only work on certain versions of the app (see below).

* If you specify behat_ionic_dirroot, files in this location will be used to determine the app version. (If you also specify behat_ionic_wwwroot, this will not be used to determine the app version, but you should ensure that the version of the running app is the same as the version of the code in behat_ionic_dirroot.)
* If you only specify behat_ionic_wwwroot, the version number will be taken from the running app, so you must ensure the app is running when you run the Behat init command, not only when you start tests. You will get an error if it isn't. (This version detection only works with app version 3.6.1 and above; for older versions you must specify behat_ionic_dirroot.)

The detected version number will be displayed in the output from the init command:

$ php admin/tool/behat/cli/init.php
You are already using composer version 1.8.4 (stable channel).
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
Nothing to install or update
Generating autoload files
Behat test environment already installed
'''Configured app tests for version 3.6.1'''
2.5 behat profile detected, automatically converted to current 3.x format
Acceptance tests environment enabled on http://localhost/core-moodle-github, to run the tests use:
vendor/bin/behat --config C:/mylocation/behat/behat.yml

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

After adding a test with one of these tags (or changing the app version used for testing), make sure you re-run Behat init; it is the init step that decides which tests to include.

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-12T13:45:14Z

Quen: /* Versioning */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment. There are two ways to do this: you can either set up your own environment manually (which will be useful if you intend to submit changes or bugfixes to the core app), or you can use Docker to set up a virtual environment.

However you set up the environment, if you update the app, you must re-run Behat init on the corresponding Moodle installation so that it knows about the newer app version.

==== Setting up the environment yourself ====

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.

==== Setting up the environment using Docker ====

(For this to work, you must have a Docker installation and know roughly how to use it.)

You can run the app using a Docker image provided by Moodle HQ, with commands like these:

* Specific version 3.6.1

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.1

* Latest stable version:

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest

* Nightly build of the next release

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing.

If you are using a local installation of the app, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself before running any Behat tests, and also kill it yourself once you are finished with it.

If you have installed the development environment locally, you can launch it using <tt>ionic serve -b</tt>. After launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

If you run it using Docker, it will automatically start up and you will see similar output.

However you launched it, to use it in Behat, add this line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

When you run Behat init, the system needs to know which version of the app you are running. This is used in order to select tests that only work on certain versions of the app (see below).

* If you specify behat_ionic_dirroot, files in this location will be used to determine the app version. (If you also specify behat_ionic_wwwroot, this will not be used to determine the app version, but you should ensure that the version of the running app is the same as the version of the code in behat_ionic_dirroot.)
* If you only specify behat_ionic_wwwroot, the version number will be taken from the running app, so you must ensure the app is running when you run the Behat init command, not only when you start tests. You will get an error if it isn't. (This version detection only works with app version 3.6.1 and above; for older versions you must specify behat_ionic_dirroot.)

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

After adding a test with one of these tags (or changing the app version used for testing), make sure you re-run Behat init; it is the init step that decides which tests to include.

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-12T13:43:41Z

Quen:

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment. There are two ways to do this: you can either set up your own environment manually (which will be useful if you intend to submit changes or bugfixes to the core app), or you can use Docker to set up a virtual environment.

However you set up the environment, if you update the app, you must re-run Behat init on the corresponding Moodle installation so that it knows about the newer app version.

==== Setting up the environment yourself ====

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.

==== Setting up the environment using Docker ====

(For this to work, you must have a Docker installation and know roughly how to use it.)

You can run the app using a Docker image provided by Moodle HQ, with commands like these:

* Specific version 3.6.1

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.1

* Latest stable version:

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest

* Nightly build of the next release

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing.

If you are using a local installation of the app, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself before running any Behat tests, and also kill it yourself once you are finished with it.

If you have installed the development environment locally, you can launch it using <tt>ionic serve -b</tt>. After launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

If you run it using Docker, it will automatically start up and you will see similar output.

However you launched it, to use it in Behat, add this line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

When you run Behat init, the system needs to know which version of the app you are running. This is used in order to select tests that only work on certain versions of the app (see below).

* If you specify behat_ionic_dirroot, files in this location will be used to determine the app version. (If you also specify behat_ionic_wwwroot, this will not be used to determine the app version, but you should ensure that the version of the running app is the same as the version of the code in behat_ionic_dirroot.)
* If you only specify behat_ionic_wwwroot, the version number will be taken from the running app, so you must ensure the app is running when you run the Behat init command, not only when you start tests. You will get an error if it isn't. (This version detection only works with app version 3.6.1 and above; for older versions you must specify behat_ionic_dirroot.)

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-12T13:42:38Z

Quen: /* Manually launch the app environment yourself */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment. There are two ways to do this: you can either set up your own environment manually (which will be useful if you intend to submit changes or bugfixes to the core app), or you can use Docker to set up a virtual environment.

However you set up the environment, if you update the app, you must re-run Behat init on the corresponding Moodle installation so that it knows about the newer app version.

==== Setting up the environment yourself ====

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.

==== Setting up the environment using Docker ====

(For this to work, you must have a Docker installation and know roughly how to use it.)

You can run the app using a Docker image provided by Moodle HQ, with commands like these:

* Specific version 3.6.1

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.1

* Latest stable version:

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest

* Nightly build of the next release

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing.

If you are using a local installation of the app, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself before running any Behat tests, and also kill it yourself once you are finished with it.

If you have installed the development environment locally, you can launch it using <tt>ionic serve -b</tt>. After launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

If you run it using Docker, it will automatically start up and you will see similar output.

However you launched it, to use it in Behat, add this line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

==== App version detection ====

When you run Behat init, the system needs to know which version of the app you are running. This is used in order to select tests that only work on certain versions of the app (see below).

* If you specify behat_ionic_dirroot, files in this location will be used to determine the app version. (If you also specify behat_ionic_wwwroot, this will not be used to determine the app version, but you should ensure that the version of the running app is the same as the version of the code in behat_ionic_dirroot.)
* If you only specify behat_ionic_wwwroot, the version number will be taken from the running app, so you must ensure the app is running when you run the Behat init command, not only when you start tests. You will get an error if it isn't. (This version detection only works with app version 3.6.1 and above; for older versions you must specify behat_ionic_dirroot.)

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-12T13:42:17Z

Quen: /* Add the mobile app Behat configuration */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment. There are two ways to do this: you can either set up your own environment manually (which will be useful if you intend to submit changes or bugfixes to the core app), or you can use Docker to set up a virtual environment.

However you set up the environment, if you update the app, you must re-run Behat init on the corresponding Moodle installation so that it knows about the newer app version.

==== Setting up the environment yourself ====

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.

==== Setting up the environment using Docker ====

(For this to work, you must have a Docker installation and know roughly how to use it.)

You can run the app using a Docker image provided by Moodle HQ, with commands like these:

* Specific version 3.6.1

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.1

* Latest stable version:

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest

* Nightly build of the next release

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing.

If you are using a local installation of the app, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself before running any Behat tests, and also kill it yourself once you are finished with it.

If you have installed the development environment locally, you can launch it using tt>ionic serve -b</tt>. After launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

If you run it using Docker, it will automatically start up and you will see similar output.

However you launched it, to use it in Behat, add this line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

==== App version detection ====

When you run Behat init, the system needs to know which version of the app you are running. This is used in order to select tests that only work on certain versions of the app (see below).

* If you specify behat_ionic_dirroot, files in this location will be used to determine the app version. (If you also specify behat_ionic_wwwroot, this will not be used to determine the app version, but you should ensure that the version of the running app is the same as the version of the code in behat_ionic_dirroot.)
* If you only specify behat_ionic_wwwroot, the version number will be taken from the running app, so you must ensure the app is running when you run the Behat init command, not only when you start tests. You will get an error if it isn't. (This version detection only works with app version 3.6.1 and above; for older versions you must specify behat_ionic_dirroot.)

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-12T12:40:52Z

Quen: /* Set up a mobile app development environment */ Added information about Docker use

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment. There are two ways to do this: you can either set up your own environment manually (which will be useful if you intend to submit changes or bugfixes to the core app), or you can use Docker to set up a virtual environment.

However you set up the environment, if you update the app, you must re-run Behat init on the corresponding Moodle installation so that it knows about the newer app version.

==== Setting up the environment yourself ====

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.

==== Setting up the environment using Docker ====

(For this to work, you must have a Docker installation and know roughly how to use it.)

You can run the app using a Docker image provided by Moodle HQ, with commands like these:

* Specific version 3.6.1

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.1

* Latest stable version:

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest

* Nightly build of the next release

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-12T10:15:16Z

Quen: /* Debugging tests */ Changed name of JavaScript functions

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behat.setField('Password', 'student2')</tt>
* <tt>behat.press('Log in', 'Forgotten')</tt>
* <tt>behat.pressStandard('back')</tt>

There are a few other functions in the 'behat' object; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-02-11T16:42:09Z

Quen: Rename the config variables

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_ionic_dirroot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behatSetField('Password', 'student2')</tt>
* <tt>behatPress('Log in', 'Forgotten')</tt>
* <tt>behatPressStandard('back')</tt>

There are a few others which all begin with 'behat'; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-01-15T18:20:00Z

Quen: /* Let Behat launch the app environment */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that has the @app tag. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behatSetField('Password', 'student2')</tt>
* <tt>behatPress('Log in', 'Forgotten')</tt>
* <tt>behatPressStandard('back')</tt>

There are a few others which all begin with 'behat'; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-01-15T17:53:24Z

Quen: Added a complete example feature file.

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

=== A complete example ===

This example is a complete feature file that loads the app, clicks on a course, and checks the app has now gone to the course page.

<code>
@app @javascript
Feature: Test app (demo)
In order to test something in the app
As a developer
I need for this test script to run the app

Background:
Given the following "courses" exist:
| fullname | shortname |
| Course 1 | C1 |
And the following "users" exist:
| username |
| student1 |
And the following "course enrolments" exist:
| user | course | role |
| student1 | C1 | student |

Scenario: Try going into the course
When I enter the app
And I log in as "student1"
And I press "Course 1" near "Course overview" in the app
Then the header should be "Course 1" in the app
</code>

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behatSetField('Password', 'student2')</tt>
* <tt>behatPress('Log in', 'Forgotten')</tt>
* <tt>behatPressStandard('back')</tt>

There are a few others which all begin with 'behat'; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-01-15T17:50:38Z

Quen: Added some help about using commands in the developer console.

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

=== Debugging tests ===

If you insert a pause into your test and open the developer tools (F12), you can see log information in the console about which actions were carried out so far, and whether Behat is waiting for anything. Here is an example:

<code>
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.28 PENDING-:
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY
VM649:391 BEHAT: 17:45:16.653 PENDING-:
</code>

While the test is paused you can also carry out some of the app Behat steps manually by typing commands into the console, which is convenient if you're not quite sure what command would work. Here are examples of the most useful commands:

* <tt>behatSetField('Password', 'student2')</tt>
* <tt>behatPress('Log in', 'Forgotten')</tt>
* <tt>behatPressStandard('back')</tt>

There are a few others which all begin with 'behat'; try using the browser's autocomplete to see the options.

Acceptance testing for the Moodle App

2019-01-15T17:43:52Z

Quen: /* Standard test steps */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Before the app starts ====

Before starting the app, you normally need to set up information in Moodle (e.g. creating a course and user). For this part of your test you can obviously use all the normal Moodle steps.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "640x360"</tt> is a useful step if you need to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

Acceptance testing for the Moodle App

2019-01-15T17:41:29Z

Quen: /* Actions */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps.

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "360x640"</tt> is a useful background step if you want your tests to run in mobile phone (rather than tablet/desktop) format. You can also use this step mid-test to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

Acceptance testing for the Moodle App

2019-01-15T17:41:15Z

Quen: /* Log in to the app */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

To log in:

<tt>When '''I log in as "student1"'''</tt>

This is the same step as used to log into standard Moodle, but if you are on the app login page it will automatically work to log into the app instead. It will log in with the given username, using the same password as username. You will then be left at the start page.

=== Actions ===

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "360x640"</tt> is a useful background step if you want your tests to run in mobile phone (rather than tablet/desktop) format. You can also use this step mid-test to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

Moodle Desktop

2019-01-14T14:31:39Z

Quen:

{{Moodle Mobile}}

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

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

Privacy API

2018-11-28T09:57:23Z

Quen: Corrected text explanation on the userlist example so it actually says what the function is doing

The [https://en.wikipedia.org/wiki/General_Data_Protection_Regulation General Data Protection Regulation] (GDPR) is an EU directive that looks at providing users with more control over their data and how it is processed. This regulation will come into effect on 25th of May 2018 and covers any citizen or permanent resident of the European Union. The directive will be respected by a number of other countries outside of the European Union.

To help institutions become compliant with this new regulation we are adding functionality to Moodle. This includes a number of components, amongst others these include a user’s right to:

* request information on the types of personal data held, the instances of that data, and the deletion policy for each;
* access all of their data; and
* be forgotten.

The compliance requirements also extend to installed plugins (including third party plugins). These need to also be able to report what information they store or process regarding users, and have the ability to provide and delete data for a user request.

This document describes the proposed API changes required for plugins which will allow a Moodle installation to become GDPR compliant.

Target Audience: The intended audience for this document is Moodle plugin developers, who are aiming to ensure their plugins are updated to comply with GDPR requirements coming into effect in the EU in May, 2018.

==Personal data in Moodle==

From the GDPR Spec, Article 4:

''‘personal data’ means any information relating to an identified or identifiable natural person (‘data subject’); an identifiable natural person is one who can be identified, directly or indirectly, in particular by reference to an identifier such as a name, an identification number, location data, an online identifier or to one or more factors specific to the physical, physiological, genetic, mental, economic, cultural or social identity of that natural person;''

In Moodle, we need to consider two main types of personal data; information entered by the user and information stored about the user. The key difference being that information stored about the user will have come from a source other than the user themselves. Both types of data can be used to form a profile of the individual.

The most obvious clue to finding personal data entered by the user is the presence of a userid on a database field. Any data on the record (or linked records) pertaining to that user may be deemed personal data for that user, including things like timestamps and record identification numbers. Additionally, any free text field which allows the user to enter information must also be considered to be the personal data of that user.

Data stored about the user includes things like ratings and comments made on a student submission. These may have been made by an assessor or teacher, but are considered the personal data of the student, as they are considered a reflection of the user’s competency in the subject matter and can be used to form a profile of that individual.

The sections that follow outline what you need to do as a plugin developer to ensure any personal data is advertised and can be accessed and deleted according to the GDPR requirements.

==Background==

===Architecture overview===

[[File:MoodlePrivacyMetadataUML.png|thumb|UML diagram of the metadata part of the privacy subsystem]]
[[File:MoodlePrivacyRequestUML.png|thumb|UML diagram of the request providers part of the privacy subsystem]]

A new system for Privacy has been created within Moodle. This is broken down into several main parts and forms the ''core_privacy'' subsystem:

* Some metadata providers - a set of PHP interfaces to be implemented by components for that component to describe the kind of data that it stores, and the purpose for its storage;
* Some request providers - a set of PHP interfaces to be implemented by components to allow that component to act upon user requests such as the Right to be Forgotten, and a Subject Access Request; and
* A manager - a concrete class used to bridge components which implement the providers with tools which request their data.

All plugins will implement one metadata provider, and zero, one or two request providers.

The 'request' providers are responsible for several separate areas:

# Detecting in which Moodle contexts a specific user has any personal data;
# Exporting all personal data from each of those contexts for that user;
# Deleting all personal data from each of those contexts for that user;
# Detecting which users have personal data in a specific Moodle context;
# Deleting all personal data for each of those users in that context; and
# Deleting all personal data for all users in a specific context.

The export and delete phases use data from the detection phase, which allows for the possibility to exclude all data from certain contexts, as required.

Please refer to the inline phpdocs of the [https://github.com/moodle/moodle/blob/v3.5.0/privacy/classes/manager.php#L31 core_privacy::manager class] for detailed description of the interfaces, their hierarchy and meaning.

Please note that support for locating and removing multiple users in a single context was added in MDL-62560 for Moodle 3.6, 3.5.3, and 3.4.6.
This functionality has been added to allow support for removal of user data for users subject to speific role criterion, and to support expiry of the same data by role too.

===Implementing a provider===

All plugins will need to create a concrete class which implements the relevant metadata and request providers. The exact providers you need to implement will depend on what data you store, and the type of plugin. This is covered in more detail in the following sections of the document.

In order to do so:

# You must create a class called ''provider'' within the namespace ''\your_pluginname\privacy''.
# This class must be created at ''path/to/your/plugin/classes/privacy/provider.php''.
# You must have your class implement the relevant metadata and request interfaces.

==Plugins which do not store personal data==

Many Moodle plugins do not store any personal data. This is usually the case for plugins which just add functionality, or which display the data already stored elsewhere in Moodle.

Some examples of plugin types which might fit this criteria include themes, blocks, filters, editor plugins, etc.

Plugins which cause data to be stored elsewhere in Moodle (e.g. via a subsystem call) are considered to store data.

One examples of a plugin which does not store any data would be the Calendar month block which just displays a view of the user’s calendar. It does not store any data itself.

An example of a plugin which must not use the null provider is the Comments block. The comments block is responsible for data subsequently being stored within Moodle. Although the block doesn’t store anything itself, it interacts with the comments subsystem and is the only component which knows how that data maps to a user.

===Implementation requirements===

In order to let Moodle know that you have audited your plugin, and that you do not store any personal user data, you must implement the ''\core_privacy\local\metadata\null_provider'' interface in your plugin’s provider.

These null providers can only be implemented where a plugin has:

* no external links (e.g. sends data to an external service like an LTI provider, repository plugin which you can search on)
* no database tables which store user data (including IP addresses)
* no user preferences

The ''null_provider'' requires you to define one function ''get_reason()'' which returns the language string identifier within your component.

====Example====

''blocks/calendar_month/classes/privacy/provider.php''

<code php>
<?php
// …

namespace block_calendar_month\privacy;

class provider implements
// This plugin does not store any personal user data.
\core_privacy\local\metadata\null_provider {

/**
* Get the language string identifier with the component's language
* file to explain why this plugin stores no data.
*
* @return string
*/
public static function get_reason() : string {
return 'privacy:metadata';
}
}
</code>

''blocks/calendar_month/lang/en/block_calendar_month.php''

<code php>
<?php
// …

...
$string['privacy:metadata'] = 'The Calendar block only displays existing calendar data.';
...
</code>

That’s it. Congratulations, your plugin now implements the Privacy API.

==Plugins which store personal data==

Many Moodle plugins do store some form of personal data.

In some cases this will be stored within database tables in your plugin, and in other cases this will be in one of Moodle’s core subsystems - for example your plugin may store files, ratings, comments, or tags.

Plugins which do store data will need to:

* Describe the type of data that they store;
* Provide a way to export that data; and
* Provide a way to delete that data.

Data is described via a ''metadata'' provider, and it is both exported and deleted via an implementation of a ''request'' provider.

These are both explained in the sections below.

===Describing the type of data you store===

In order to describe the type of data that you store, you must implement the ''\core_privacy\local\metadata\provider'' interface.

This interfaces requires that you define one function: ''get_metadata''.

There are several types of item to describe the data that you store. These are for:

* Items in the Moodle database;
* Items stored by you in a Moodle subsystem - for example files, and ratings; and
* User preferences stored site-wide within Moodle for your plugin

Note: All fields should include a description from a language string within your plugin.

====Example====

''mod/forum/classes/privacy/provider.php''

<code php>
<?php
// …

namespace mod_forum\privacy;
use core_privacy\local\metadata\collection;

class provider implements
// This plugin does store personal user data.
\core_privacy\local\metadata\provider {

public static function get_metadata(collection $collection) : collection {

// Here you will add more items into the collection.

return $collection;
}
}
</code>

====Indicating that you store content in a Moodle subsystem====

Many plugins will use one of the core Moodle subsystems to store data.

As a plugin developer we do not expect you to describe those subsystems in detail, but we do need to know that you use them and to know what you use them for.

You can indicate this by calling the ''add_subsystem_link()'' method on the ''collection''.

=====Relevant subsystems=====

You are likely to need to indicate use of the following subsystems that store user data:

* Ratings (if users are allowed to rate items within your plugin)
* Tags (if users can tag items within your plugin)
* Comments (if users can make comments on items in your plugin)
* Questions (if the plugin uses core question types)
* Filesystem (if users can attach files to items within your plugin)
* ...?

Some subsystems which store user data do not need to be listed:

* (TBC - how about global search? Nothing lists it that I could see.)

=====Example=====

''mod/forum/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->add_subsystem_link(
'core_files',
[],
'privacy:metadata:core_files'
);

return $collection;
}
</code>

''mod/forum/lang/en/forum.php''

<code php>
<?php

$string['privacy:metadata:core_files'] = 'The forum stores files which have been uploaded by the user to form part of a forum post.';
</code>

====Describing data stored in database tables====

Most Moodle plugins will store some form of user data in their own database tables.

As a plugin developer you will need to describe each database table, and each field which includes user data.

It is a matter of judgement which fields contain user data and which don't. Anything entered by, or directly about, the user probably counts as user data but it may be useful to include additional fields that explain the context of the data.

=====Example=====

''mod/forum/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->add_database_table(
'forum_discussion_subs',
[
'userid' => 'privacy:metadata:forum_discussion_subs:userid',
'discussionid' => 'privacy:metadata:forum_discussion_subs:discussionid',
'preference' => 'privacy:metadata:forum_discussion_subs:preference',

],
'privacy:metadata:forum_discussion_subs'
);

return $collection;
}
</code>

''mod/forum/lang/en/forum.php''

<code php>
<?php

$string['privacy:metadata:forum_discussion_subs'] = 'Information about the subscriptions to individual forum discussions. This includes when a user has chosen to subscribe to a discussion, or to unsubscribe from one where they would otherwise be subscribed.';
$string['privacy:metadata:forum_discussion_subs:userid'] = 'The ID of the user with this subscription preference.';
$string['privacy:metadata:forum_discussion_subs:discussionid'] = 'The ID of the discussion that was subscribed to.';
$string['privacy:metadata:forum_discussion_subs:preference'] = 'The start time of the subscription.';
</code>

====Indicating that you store site-wide user preferences====

Many plugins will include one or more user preferences. Unfortunately this is one of Moodle’s older components and many of the values stored are not pure user preferences. Each plugin should be aware of how it handles its own preferences and is best placed to determine whether they are site-wide preferences, or per-instance preferences.

Whilst most of these will have a fixed name (e.g. ''filepicker_recentrepository''), some will include a variable of some kind (e.g. ''tool_usertours_tour_completion_time_2''). Only the general name (in this case "tool_usertours_tour_completion_time_") needs to be indicated, rather than one copy for each possible value of the variable.

Also, these should only be ''site-wide'' user preferences which do not belong to a specific Moodle context.

In the above examples:

* Preference ''filepicker_recentrepository'' belongs to the file subsystem, and is a site-wide preference affecting the user anywhere that they view the filepicker.
* Preference ''tool_usertours_tour_completion_time_2'' belongs to user tours. User tours are a site-wide feature which can affect many parts of Moodle and cross multiple contexts.

In some cases a value may be stored in the preferences table but is known to belong to a specific context within Moodle. In these cases they should be stored as metadata against that context rather than as a site-wide user preference.

You can indicate this by calling the ''add_user_preference()'' method on the ''collection''.

Any plugin providing user preferences must also implement the ''\core_privacy\local\request\preference_provider''.

=====Example=====

''admin/tool/usertours/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->add_user_preference('tool_usertours_tour_completion_time',
'privacy:metadata:preference:tool_usertours_tour_completion_time');

return $collection;
}
</code>

''admin/tool/usertours/lang/en/tool_usertours.php''

<code php>
<?php

$string['privacy:metadata:tool_usertours_tour_completion_time'] = 'The time that a specific user tour was last completed by a user.';
</code>

====Indicating that you export data to an external location====

Many plugins will interact with external systems - for example cloud-based services. Often this external location is configurable within the plugin either at the site or the instance level.

As a plugin developer you will need to describe each ''type'' of target destination, alongside a list of each exported field which includes user data.
The ''actual'' destination does not need to be described as this can change based on configuration.

You can indicate this by calling the ''add_external_location_link()'' method on the collection.

=====Example=====

''mod/lti/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->add_external_location_link('lti_client', [
'userid' => 'privacy:metadata:lti_client:userid',
'fullname' => 'privacy:metadata:lti_client:fullname',
], 'privacy:metadata:lti_client');

return $collection;
}
</code>

''mod/lti/lang/en/lti.php''

<code php>
<?php

$string['privacy:metadata:lti_client'] = 'In order to integrate with a remote LTI service, user data needs to be exchanged with that service.';
$string['privacy:metadata:lti_client:userid'] = 'The userid is sent from Moodle to allow you to access your data on the remote system.';
$string['privacy:metadata:lti_client:fullname'] = 'Your full name is sent to the remote system to allow a better user experience.';
</code>

===Providing a way to export user data===

In order to export the user data that you store, you must implement the relevant request provider.

We have named these request providers because they are called in response to a specific request from a user to access their information, however they also deal with the removal of user data following it's expiry.

There are several different types of request provider, and you may need to implement several of these, depending on the type and nature of your plugin.

Broadly speaking plugins will fit into one of the following categories:

* Plugins which are a subplugin of another plugin. Examples include ''assignsubmission'', ''atto'', and ''datafield'';
* Plugins which are typically called by a Moodle subsystem. Examples include ''qtype'', and ''profilefield'';
* All other plugins which store data.

Most plugins will fit into this final category, whilst other plugins may fall into several categories.
Plugins which ''define'' a subplugin will also be responsible for collecting this data from their subplugins.

A final category exists - plugins which store user preferences. In some cases this may be the ''only'' provider implemented.

====Standard plugins which store data====

A majority of Moodle plugins will fit into this category and will be required to implement the ''\core_privacy\local\request\plugin\provider'' interface. This interface requires that you define four functions (the first two of which are dealt with in this section):

* ''get_contexts_for_userid'' - to explain where data is held within Moodle for your plugin; and
* ''export_user_data'' - to export a user’s personal data from your plugin.
* ''delete_data_for_all_users_in_context'' - to delete all data for all users in the specified context.
* ''delete_data_for_user'' - to delete all user data for the specified user, in the specified contexts.

These APIs make use of the Moodle ''context'' system to hierarchically store this data.

In addition to these requirements, since Moodle 3.4.6, 3.5.3, any plugin which implements the plugin provider interface must also implement the ''\core_privacy\local\request\core_userlist_provider'' provider and implement functions:

* ''get_users_in_context'' - to locate the users who hold any personal data in a specific context; and
* ''delete_data_for_users'' - to delete data for multiple users in the specified context.

=====Retrieving the list of contexts=====

You are required to return the list of contexts for which the plugin stores data about the user. These are the standard Moodle contexts - CONTEXT_COURSE, CONTEXT_USER, CONTEXT_MODULE and so on. In many cases the link between the module type and the context is self-evident (e.g. activity modules). In some cases it may be less so. For example, an enrolment plugin (that stores user data, which most don't) would link to course context (users enrol in courses). Other types of plugins may be less obvious but you need to pick something. One way might to consider what context you would use when checking role capabilities. Consider that this will be used to structure the exported data and define what data is deleted when a context is expired.

Contexts are retrieved using the ''get_contexts_for_userid'' function which takes the ID of the user being fetched, and returns a list of contexts in which the user has any data.

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The list of contexts used in this plugin.
*/
public static function get_contexts_for_userid(int $userid) : contextlist {}
</code>

The function returns a ''\core_privacy\local\request\contextlist'' which is used to keep a set of contexts together in a fixed fashion.

Because a Subject Access Request covers ''every'' piece of data that is held for a user within Moodle, efficiency and performance is highly important. As a result, contexts are added to the ''contextlist'' by defining one or more SQL queries which return just the contextid. Multiple SQL queries can be added as required.

Many plugins will interact with specific subsystems and store data within them.
These subsystems will also provide a way in which to link the data that you have stored with your own database tables.
At present these are still a work in progress and only the ''core_ratings'' subsystem includes this.

======Basic example======

The following example simply fetches the contextid for all forums where a user has a single discussion (note: this is an incomplete example):

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The list of contexts used in this plugin.
*/
public static function get_contexts_for_userid(int $userid) : contextlist {
$contextlist = new \core_privacy\local\request\contextlist();

$sql = "SELECT c.id
FROM {context} c
INNER JOIN {course_modules} cm ON cm.id = c.instanceid AND c.contextlevel = :contextlevel
INNER JOIN {modules} m ON m.id = cm.module AND m.name = :modname
INNER JOIN {forum} f ON f.id = cm.instance
LEFT JOIN {forum_discussions} d ON d.forum = f.id
WHERE (
d.userid = :discussionuserid
)
";

$params = [
'modname' => 'forum',
'contextlevel' => CONTEXT_MODULE,
'discussionuserid' => $userid,
];

$contextlist->add_from_sql($sql, $params);

return $contextlist;
}
</code>

======More complete example======

The following example includes a link to core_rating.
It will find any forum, forum discussion, or forum post where the user has any data, including:

* Per-forum digest preferences;
* Per-forum subscription preferences;
* Per-forum read tracking preferences;
* Per-discussion subscription preferences;
* Per-post read data (if a user has read a post or not); and
* Per-post rating data.

In the case of the rating data, this will include any post where the user has rated the post of another user.

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The list of contexts used in this plugin.
*/
public static function get_contexts_for_userid(int $userid) : contextlist {
$ratingsql = \core_rating\privacy\provider::get_sql_join('rat', 'mod_forum', 'post', 'p.id', $userid);
// Fetch all forum discussions, and forum posts.
$sql = "SELECT c.id
FROM {context} c
INNER JOIN {course_modules} cm ON cm.id = c.instanceid AND c.contextlevel = :contextlevel
INNER JOIN {modules} m ON m.id = cm.module AND m.name = :modname
INNER JOIN {forum} f ON f.id = cm.instance
LEFT JOIN {forum_discussions} d ON d.forum = f.id
LEFT JOIN {forum_posts} p ON p.discussion = d.id
LEFT JOIN {forum_digests} dig ON dig.forum = f.id
LEFT JOIN {forum_subscriptions} sub ON sub.forum = f.id
LEFT JOIN {forum_track_prefs} pref ON pref.forumid = f.id
LEFT JOIN {forum_read} hasread ON hasread.forumid = f.id
LEFT JOIN {forum_discussion_subs} dsub ON dsub.forum = f.id
{$ratingsql->join}
WHERE (
p.userid = :postuserid OR
d.userid = :discussionuserid OR
dig.userid = :digestuserid OR
sub.userid = :subuserid OR
pref.userid = :prefuserid OR
hasread.userid = :hasreaduserid OR
dsub.userid = :dsubuserid OR
{$ratingsql->userwhere}
)
";

$params = [
'modname' => 'forum',
'contextlevel' => CONTEXT_MODULE,
'postuserid' => $userid,
'discussionuserid' => $userid,
'digestuserid' => $userid,
'subuserid' => $userid,
'prefuserid' => $userid,
'hasreaduserid' => $userid,
'dsubuserid' => $userid,
];
$params += $ratingsql->params;

$contextlist = new \core_privacy\local\request\contextlist();
$contextlist->add_from_sql($sql, $params);

return $contextlist;

}
</code>

=====Retrieving the users in a context=====

You are required to return the list of users holding personal data in a context for which the plugin stores data about the user.
This method is very similar to the ''get_contexts_for_userid'' function but has some important distinctions:

* It takes a ''userlist'' as an argument and does not require that you, as a developer, create it yourself;
* There is no need to return any value; and
* The argument for the ''userlist::add_from_sql'' are different to those for ''contextlist::add_from_sql'' (this is because we learnt some important lessons after the initial implementation).

<code php>
/**
* Get the list of users who have data within a context.
*
* @param userlist $userlist The userlist containing the list of users who have data in this context/plugin combination.
*/
public static function get_users_in_context(userlist $userlist) {}
</code>

======Basic example======

The following example simply fetches the userid for all users in a given forum context, who created a discussion or a post in that forum (note: this is an incomplete example):

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The list of contexts used in this plugin.
*/
public static function get_contexts_for_userid(int $userid) : contextlist {

$context = $userlist->get_context();

if (!$context instanceof \context_module) {
return;
}

$params = [
'instanceid' => $context->instanceid,
'modulename' => 'forum',
];

// Discussion authors.
$sql = "SELECT d.userid
FROM {course_modules} cm
JOIN {modules} m ON m.id = cm.module AND m.name = :modulename
JOIN {forum} f ON f.id = cm.instance
JOIN {forum_discussions} d ON d.forum = f.id
WHERE cm.id = :instanceid";
$userlist->add_from_sql('userid', $sql, $params);

// Forum authors.
$sql = "SELECT p.userid
FROM {course_modules} cm
JOIN {modules} m ON m.id = cm.module AND m.name = :modulename
JOIN {forum} f ON f.id = cm.instance
JOIN {forum_discussions} d ON d.forum = f.id
JOIN {forum_posts} p ON d.id = p.discussion
WHERE cm.id = :instanceid";
$userlist->add_from_sql('userid', $sql, $params);

// ...
}
</code>

=====Exporting user data=====

After determining where in Moodle your plugin holds data about a user, the ''\core_privacy\manager'' will then ask your plugin to export all user data for a subset of those locations.

This is achieved through use of the ''export_user_data'' function which takes the list of approved contexts in a ''\core_privacy\local\request\approved_contextlist'' object.

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Export all user data for the specified user, in the specified contexts, using the supplied exporter instance.
*
* @param approved_contextlist $contextlist The approved contexts to export information for.
*/
public static function export_user_data(approved_contextlist $contextlist) {}
</code>

The ''approved_contextlist'' includes both the user record, and a list of contexts, which can be retrieved by either processing it as an Iterator, or by calling ''get_contextids()'' or ''get_contexts()'' as required.

Data is exported using a ''\core_privacy\local\request\content_writer'', which is described in further detail below.

====Plugins which store user preferences====

Many plugins store a variety of user preferences, and must therefore export them.

Since user preferences are a site-wide preference, these are exported separately to other user data.
In some cases the only data present is user preference data, whilst in others there is a combination of user-provided data, and user preferences.

Storing of user preferences is achieved through implementation of the ''\core_privacy\local\request\user_preference_provider'' interface which defines one required function -- ''export_user_preferences''.

You need to provide a description of the value of the user preference. (This description is particularly useful in cases where the value might be, say, 3, but it actually means 'Alphabetical order'.) Most likely you can use an existing language string from your plugin.

=====Example=====

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Export all user preferences for the plugin.
*
* @param int $userid The userid of the user whose data is to be exported.
*/
public static function export_user_preferences(int $userid) {
$markasreadonnotification = get_user_preference('markasreadonnotification', null, $userid);
if (null !== $markasreadonnotification) {
switch ($markasreadonnotification) {
case 0:
$markasreadonnotificationdescription = get_string('markasreadonnotificationno', 'mod_forum');
break;
case 1:
default:
$markasreadonnotificationdescription = get_string('markasreadonnotificationyes', 'mod_forum');
break;
}
writer::export_user_preference('mod_forum', 'markasreadonnotification', $markasreadonnotification, $markasreadonnotificationdescription);
}
}
</code>

==== Plugins which can have own subplugins ====

Many plugin types are also able to define their own subplugins and will need to define a contract between themselves and their subplugins in order to fetch their data.

This is required as the parent plugin and the child subplugin should be separate entities and the parent plugin must be able to function if one or more of its subplugins are uninstalled.

The parent plugin is responsible for defining the contract, and for interacting with its subplugins, though we intend to create helpers to make this easier.

The parent plugin should define a new interface for each type of subplugin that it defines. This interface should extend the ''\core_privacy\local\request\plugin\subplugin_provider'' interface.

===== When a parent plugin should and should not provide the interface for its subplugins =====

There can be cases when there is no point for a plugin to provide the "subplugin_provider" based interface, even if it has own subplugins. See the Atto or TinyMCE editors as real examples.

If the parent plugin has no data passed through to the subplugins, there is no benefit in defining a subplugin provider. For example, Atto subplugins are just used to enhance the functionality and they never receive anything like a context. Most of the time we need to define a subplugin provider, but in cases where there is no data passed from the plugin to its subplugins, there is no need to define the subplugin provider. If the subplugins still do store personal data that are not related to the parent plugin in any way, then subplugins should define their own standard provider.

Compare with something like mod_assign where the subplugins store data for the parent and that data is contextually relevant to the parent plugin. In those cases the subplugin stores data for the plugin and it only makes sense to do so in the context of its parent plugin.

=====Example=====

The following example defines the contract that assign submission subplugins may be required to implement.

The assignment module is responsible for returning the contexts of all assignments where a user has data, but in some cases it is unaware of all of those cases - for example if a Teacher comments on a student submission it may not be aware of these as the information about this interaction may not be stored within its own tables.

''mod/assign/privacy/assignsubmission_provider.php''

<code php>
<?php
// …

namespace mod_assign\privacy;
use \core_privacy\local\metadata\collection;

interface assignsubmission_provider extends
// This Interface defines a subplugin.
\core_privacy\local\request\plugin\subplugin_provider {

/**
* Get the SQL required to find all submission items where this user has had any involvements.
*
* @param int $userid The user to search.
* @return \stdClass Object containing the join, params, and where used to select a these records from the database.
*/
public static function get_items_with_user_interaction(int $userid) : \stdClass ;

/**
* Export all relevant user submissions information which match the combination of userid and attemptid.
*
* @param int $userid The user to search.
* @param \context $context The context to export this submission against.
* @param array $subcontext The subcontext within the context to export this information
* @param int $attid The id of the submission to export.
*/
public static function export_user_submissions(int $userid, \context $context, array $subcontext, int $attid) ;

}
</code>

====Plugins which are subplugins to another plugin====

If you are developing a sub-plugin of another plugin, then you will have to look at the relevant plugin in order to determine the exact contract.

Each subplugin type should define a new interface which extends the ''\core_privacy\local\request\plugin\subplugin_provider'' interface and it is up to the parent plugin to define how they will interact with their children.

The principles remain the same, but the exact implementation will differ depending upon requirements.

''mod/pluginname/classes/privacy/provider.php''

<code php>
<?php
// …
namespace assignsubmission\onlinetext;

class provider implements
// This plugin does store personal user data.
\core_privacy\local\metadata\provider,

// This plugin is a subplugin of assign and must meet that contract.
\mod_assign\privacy\assignsubmission_provider {
}
</code>

====Plugins which are typically called by a Moodle subsystem====

There are a number of plugintypes in Moodle which are typically called by a specific Moodle subsystem.

Some of these are ''only'' called by that subsystem, for example plugins which are of the ''plagiarism'' plugintype should never be called directly, but are always invoked via the ''core_plagiarism'' subsystem.

Conversely, there maybe other plugintypes which can be called both via a subsystem, and in some other fashion. We are still determining whether any plugintypes currently fit this pattern.

If you are developing a plugin which belongs to a specific subsystem, then you will have to look at the relevant plugin in order to determine the exact contract.

Each subsystem will define a new interface which extends the ''\core_privacy\local\request\plugin\subsystem_provider'' interface and it is up to that subsystem to define how they will interact with those plugins.

The principles remain the same, but the exact implementation will differ depending upon requirements.

''plagiarism/detectorator/classes/privacy/provider.php''

<code php>
<?php
// …
namespace plagiarism_detectorator\privacy;

class provider implements
// This plugin does export personal user data.
\core_privacy\local\metadata\provider,

// This plugin is always linked against another activity module via the Plagiarism API.
\core_plagiarism\privacy\plugin_provider {
}
</code>

====Exporting data====

Any plugin which stores data must also export it.

To cater for this the privacy API includes a ''\core_privacy\local\request\content_writer'', which defines a set of functions to store different types of data.

Broadly speaking data is broken into the following types:

* Data - this is the object being described. For example the post content in a forum post;
* Related data - this is data related to the object being stored. For example, ratings of a forum post;
* Metadata - This is metadata about the main object. For example whether you are subscribed to a forum discussion;
* User preferences - this is data about a site-wide preference;
* Files - Any files that you are stored within Moodle on behalf of this plugin; and
* Custom files - For custom file formats - e.g. a calendar feed for calendar data. These should be used sparingly.

Each piece of data is stored against a specific Moodle ''context'', which will define how the data is structured within the exporter.
Data, and Related data only accept the ''stdClass'' object, whilst metadata should be stored as a set of key/value pairs which include a description.

In some cases the data being stored belongs within an implicit structure. For example, one forum has many forum discussions, which each have a number of forum posts. This structure is represented by an ''array'' referred to as a ''subcontext''.

The ''content_writer'' must ''always'' be called with a specific context, and can be called as follows:

''mod/forum/classes/privacy/provider.php''

<code php>
<?php
// …
use \core_privacy\local\request\writer;

writer::with_context($context)
->export_data($subcontext, $post)
->export_area_files($subcontext, 'mod_forum', 'post', $post->id)
->export_metadata($subcontext, 'postread', (object) ['firstread' => $firstread], new \lang_string('privacy:export:post:postread'));
</code>

Any text field which supports Moodle files must also be rewritten:

''mod/forum/classes/privacy/provider.php''

<code php>
<?php
// …
use \core_privacy\local\request\writer;

$post->message = writer::with_context($context)
->rewrite_pluginfile_urls($subcontext, 'mod_forum', 'post', $post->id, $post->message);

</code>

===Providing a way to delete user data===

Deleting user data is also implemented in the request interface. There are two methods that need to be created. The first one to remove all user data from a context, the other to remove user data for a specific user in a list of contexts.

====Delete for a context====

A context is given and all user data (for all users) is to be deleted from the plugin. This will be called when the retention period for the context has expired to adhere to the privacy by design requirement. Retention periods are set in the Data registry.

Note that this will be called for '''any''' context being expired, not only those the plugin holds data for (as returned by get_contexts_for_userid()), so you must carefully check the contexts given.

When expiring content for a high-level context such as a course context, the function will be called not only with the course context but also with each context within the course: each module context, each block context, etc. At each level you should only expire data specifically related to that exact context. For a module plugin, this generally means you should only take action for CONTEXT_MODULE contexts and only if they relate to an instance of your module, as shown in the following example. (In the rare case where your module also stores user data related to the course, and not just for a module instance, then you do need to implement CONTEXT_COURSE level contexts to expire that course-level data.)

<code php>
/**
* Delete all personal data for all users in the specified context.
*
* @param context $context Context to delete data from.
*/
public static function delete_data_for_all_users_in_context(\context $context) {
global $DB;

if ($context->contextlevel != CONTEXT_MODULE) {
return;
}

$cm = get_coursemodule_from_id('choice', $context->instanceid);
if (!$cm) {
return;
}

$DB->delete_records('choice_answers', ['choiceid' => $cm->instance]);
}
</code>

====Delete personal information for a specific user and context(s)====

An ''approved_contextlist'' is given and user data related to that user should either be completely deleted, or overwritten if a structure needs to be maintained. This will be called when a user has requested the right to be forgotten. All attempts should be made to delete this data where practical while still allowing the plugin to be used by other users.

''mod/choice/classes/privacy/provider.php''

<code php>
public static function delete_data_for_user(approved_contextlist $contextlist) {
global $DB;

if (empty($contextlist->count())) {
return;
}
$userid = $contextlist->get_user()->id;
foreach ($contextlist->get_contexts() as $context) {
$instanceid = $DB->get_field('course_modules', 'instance', ['id' => $context->instanceid], MUST_EXIST);
$DB->delete_records('choice_answers', ['choiceid' => $instanceid, 'userid' => $userid]);
}
}
</code>

====Delete personal information for several users in a specific context====

An ''approved_userlist'' is given and user data related to all users in the specified context should either be completely deleted, or overwritten if a structure needs to be maintained. This will be called when a user has requested the right to be forgotten when per-role overrides exist, or when performing a per-role expiry of a context. All attempts should be made to delete this data where practical while still allowing the plugin to be used by other users.

''mod/chat/classes/privacy/provider.php''

<code php>
/**
* Delete multiple users within a single context.
*
* @param approved_userlist $userlist The approved context and user information to delete information for.
*/
public static function delete_data_for_users(approved_userlist $userlist) {
global $DB;

$context = $userlist->get_context();
$cm = $DB->get_record('course_modules', ['id' => $context->instanceid]);
$chat = $DB->get_record('chat', ['id' => $cm->instance]);

list($userinsql, $userinparams) = $DB->get_in_or_equal($userlist->get_userids(), SQL_PARAMS_NAMED);
$params = array_merge(['chatid' => $chat->id], $userinparams);
$sql = "chatid = :chatid AND userid {$userinsql}";

$DB->delete_records_select('chat_messages', $sql, $params);
$DB->delete_records_select('chat_messages_current', $sql, $params);
$DB->delete_records_select('chat_users', $sql, $params);
}
</code>

==Difference between Moodle 3.3 and more recent versions==
Moodle 3.3 has a minimum requirement of php 5.6 and so type hinting and return type declarations are not supported in this version.
Consequently the privacy API for this version does not have these features.
==Common Questions==
===What to do if you have one plugin that supports multiple branches===
This is something that we have considered and we have put in place a polyfill. This gets around the restrictions of one version having type hinting and return type declarations while another does not.

====Example====
To use the polyfill include the legacy polyfill trait and create the necessary static methods but with an underscore (shown below).
<code php>
class provider implements
\core_privacy\local\metadata\provider,
\core_privacy\local\request\plugin\provider {

// This trait must be included.
use \core_privacy\local\legacy_polyfill;

// The required methods must be in this format starting with an underscore.
public static function _get_metadata(collection $collection) {
// Code for returning metadata goes here.
}
</code>

===What to do if your plugin must implement a subplugin or subsystem plugin provider===
For subplugins (e.g. assignsubmission, assignfeedback, quiz report, quiz access rules), or subsystems which have a plugintype relationship (portfolio, plagiarism, and others), they will also define their own legacy polyfill.

In this instance you will need to include the trait for both the core polyfill, and the provider polyfill as appropriate.
==== Example ====
<code php>
class provider implements
// This plugin has data and must therefore define the metadata provider in order to describe it.
\core_privacy\local\metadata\provider,

// This is a plagiarism plugin. It interacts with the plagiarism subsystem rather than with core.
\core_plagiarism\privacy\plagiarism_provider {

// This trait must be included to provide the relevant polyfill for the metadata provider.
use \core_privacy\local\legacy_polyfill;

// This trait must be included to provide the relevant polyfill for the plagirism provider.
use \core_plagiarism\privacy\plagiarism_provider\legacy_polyfill;

// The required methods must be in this format starting with an underscore.
public static function _get_metadata(collection $collection) {
// Code for returning metadata goes here.
}

// This is one of the polyfilled methods from the plagiarism provider.
public static function _export_plagiarism_user_data($userid, \context $context, array $subcontext, array $linkarray) {
// ...
}
</code>

== Tips for development ==

* While implementing the privacy API into your plugin, there are CLI scripts that can help you to test things on the fly. Just don't forget these are not supposed to replace proper unit tests. See [[Privacy API/Utilities]] for details.
* Inherit Unit tests from the <code php>core_privacy\tests\provider_testcase</code>, not <code php>advanced_testcase</code>. Advanced test case doesn't reset the Privacy content_writer between tests!

==See also==

* [[Subject Access Request FAQ]]
* [[:en:GDPR|GDPR]] in the user documentation
* [[Privacy API/Utilities]] provides CLI scripts that are helpful during development

[[Category:Privacy]]
[[Category:GDPR]]
[[Category:API]]

Acceptance testing for the Moodle App

2018-11-27T16:59:19Z

Quen: /* Summary */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app, for example so that you can test plugins that you may have written for the app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps. To log in:

<tt>When '''I log in as "student1" in the app'''</tt>

This step can only be used on the app login page. It will log in with the given username and password. You will then be left at the start page.

=== Actions ===

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "360x640"</tt> is a useful background step if you want your tests to run in mobile phone (rather than tablet/desktop) format. You can also use this step mid-test to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

Acceptance testing for the Moodle App

2018-11-27T16:58:51Z

Quen: /* Limitations */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps. To log in:

<tt>When '''I log in as "student1" in the app'''</tt>

This step can only be used on the app login page. It will log in with the given username and password. You will then be left at the start page.

=== Actions ===

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "360x640"</tt> is a useful background step if you want your tests to run in mobile phone (rather than tablet/desktop) format. You can also use this step mid-test to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

== Limitations ==

I have split the limitations of this approach into three categories, below.

=== Fundamental limitations ===

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

=== Extra steps that might be needed ===

* There is no obvious way to attach files.

Probably there are also other extra steps that would be useful - these would be discovered by trying to write tests. At the OU we plan to write Behat tests for our plugins once this feature is approved, so we will identify and add some extra steps at that point.

=== Testing the app itself ===

This system can absolutely be used to test features built into the app as well a plugins.

However, there is a limitation, which is that currently the Behat feature files must live in the Moodle project. This may be less appropriate for app features.

A future extension of this feature could use the behat_approot variable and automatically include feature files from a directory within the app's source tree. I think this would probably be quite simple but I have not yet tried it.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.

Acceptance testing for the Moodle App

2018-11-27T14:05:26Z

Quen: /* Summary */

'''This is only a proposal, MDL-63977, and is not yet available in Moodle. Please contact sam marshall if you have any queries and do not use this information for anything yet!'''

From Moodle 3.7 if this change is accepted it will be possible to write Behat tests for mobile app features.

== Summary ==

It is now possible to create Behat tests that carry out automated functionality testing on the mobile app.

By default, these do not run as part of a normal Behat run. This page tells you how to run the tests, and how to write them.

A key point is that these tests for some parts of the mobile app are '''included within the Moodle codebase''', not within the app codebase, because they are run using the Moodle Behat infrastructure. This is definitely appropriate for Moodle plugins that add app support. It may also be acceptable for tests of the app itself, but this is not yet agreed.

The main advantages of this approach are:

* It is easy for third-party plugin authors to create tests for app features in exactly the same way that they create tests for website features.
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.
* This system does not require any mobile device hardware and should work on all common platforms.

This system has been tested on Windows 7 and Ubuntu 18.04 LTS.

== Running Behat tests for the mobile app ==

=== Set up a mobile app development environment ===

First you will need to set up a mobile app development environment.

Follow the first part of the instructions on this page:

* [[Setting up your development environment for Moodle Mobile 2]]

You need to get as far as the part in section 5 where you open the app in the browser; this is what Behat will do. You don't need to complete the later steps.

* You will need to update this environment periodically, for example when a new version of the mobile app is released. Behat does not do this for you.
* When you update the mobile app, you must re-run Behat init on the corresponding Moodle installation.

=== Add the mobile app Behat configuration ===

You need to add one or two lines to your config.php to enable app testing. First, put this line in:

<code php>
$CFG->behat_approot = '/path/to/app/workspace/moodlemobile2';
</code>

This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:

* Depending on your computer, it may take about 3 minutes to start up.
* The server uses about 1GB RAM.

There are two options, covered next.

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you don't need to add anything else to config.php.

When you do this, the Ionic server will be started automatically when Behat runs a test that uses the 'I enter the mobile app' step. It will be automatically terminated when the Behat test run finishes. If the test run includes multiple scenarios that use the app, they will all reuse the one server; it won't restart each time.

This is simple and convenient, but it is probably not a good approach for developers who frequently re-run a short Behat run (as you have to wait for it to start Ionic every time) or for complex systems that run Behat in parallel (as you may end up with multiple copies of Ionic eating up your RAM).

==== Manually launch the app environment yourself ====

The other option is to launch the Ionic server yourself (using <tt>ionic serve -b</tt>) before running any Behat tests, and also kill it yourself once you are finished with it. In this case, after launching it you will see output like:

<code>
[OK] Development server running!
Local: http://localhost:8100
External: http://137.108.5.43:8100, http://192.168.56.1:8100
</code>

To use it in Behat, add this extra line to the Moodle config.php:

<code php>
$CFG->behat_ionicaddress = 'http://localhost:8100';
</code>

The advantage of this approach is that you are in charge of bringing up and taking down the Ionic server, so you can do this efficiently, share a copy between parallel runs, etc. The disadvantage is that you do have to remember to do it; if the server isn't running, tests which use the app will fail.

The running Ionic server should correspond to the app root setting, above, because the version number from the mobile app installation is used to determine which tests to run.

== Browser profiles ==

Mobile tests only run in Chrome, so you need to make sure you have a Chrome profile set up in your config.php Behat settings.

* See [[Running acceptance test]] for more information on profiles.

Behat will automatically run app tests (those with @app tag) only in a Chrome browser profile. So, if you run multiple browser tests, it won't waste time trying to run the app tests in each one.

== Behat init ==

After you have set up the config.php, you will need to re-run Behat init:

<code php>
php admin/tool/behat/cli/init.php
</code>

This is necessary because by default, Behat won't run app tests (those with @app tag) at all, since you didn't have it configured.

== Running Behat ==

To run mobile tests in Behat, simply launch Behat in the usual way, but make sure you are using a Chrome profile. (Depending on your setup, this might mean using <tt>--profile=chrome</tt>.)

You can specify the scenarios to run as normal. The app tests all have the @app tag, so if you want to run all the mobile tests you can specify --tags=app, but you can also run any other set of scenarios. It is OK to combine app and normal tests in the same run.

== Writing tests ==

This page assumes you already know all about [[Writing acceptance tests]] in general.

=== Test structure ===

* Mobile app test scenarios should be marked <tt>@app</tt> and <tt>@javascript</tt> in addition to any other tags that may be required.
* If creating a feature file specifically for app tests, call it <tt>app_whatever.feature</tt> (i.e. use the <tt>app_</tt> prefix). This is not technically required, it's just for consistency.

You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example <tt>the following "courses" exist</tt>, and so on.

=== Start the app ===

Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:

<tt>Given '''I enter the app'''</tt>

This will:

* Set up all the Moodle server settings to allow the mobile app to connect.
* Launch Ionic if necessary
* Restart the browser. This is needed to ensure it doesn't contain any stored data from previous app testing.
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).
* Open the Ionic server address in the test Chrome browser.
* Install necessary JavaScript code in the page that supports Behat testing.
* Automatically enter the server URL into the app if necessary.

After this step completes, if it is the first time you ran the app inside this scenario, you will be left at the login screen. If you already logged in earlier, then you will be at the start page.

You can use this step even when you are already in the app; this will restart it.

=== Log in to the app ===

All the other app-specific Behat steps end with the words 'in the app' to distinguish them from the normal steps. To log in:

<tt>When '''I log in as "student1" in the app'''</tt>

This step can only be used on the app login page. It will log in with the given username and password. You will then be left at the start page.

=== Actions ===

<tt>And '''I press "Course 1" in the app'''</tt>

This finds an element which contains either the visible text, or Aria label, 'Course 1' and clicks it. It should work for links, buttons and similar.

You should be able to use this for almost any actions that would be carried out by pressing something - pressing a button, following a link, changing a checkbox, switching a switch, opening a dropdown, selecting something from the popup, etc.

For buttons that are icons with no text, you can usually find them using the Chrome inspector - look for the 'aria-label' attribute.

You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label 'home'.

* Exact matches (an element which contains only the specified text, or where the Aria label is exactly the specified text) will be preferred. If there are no exact matches, then partial ones (anything containing that text) will be considered.
* If there are multiple matches, or none, the step will fail. You can avoid this by specifying an exact match (provided there is only one exact match, this will not fail even if there are other partial matches) or by clicking on an icon instead of text.
* If the item you try to press is a label for some other form field (using <tt>ion-label</tt> and the <tt>aria-labelled-by</tt> attribute) then it will actually press the field; this is useful in the settings menus.

<tt>And '''I press "Course 1" near "Unique text" in the app'''</tt>

This is a variant of the above step which is useful when there are multiple elements with the same text on the page. The second value ('Unique text' in this example) should be some text that is unique on the page. The system will press the instance of 'Course 1' that is nearest to the supplied unique text.

(This is intended as a simpler alternative to the standard Behat steps that use the word 'in', such as <tt>I click on "X" "thing" in "Y" "css_element"</tt>. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)

* Nearest is defined in terms of the DOM rather than pixel position; it is based on the number of steps you would have to take up the tree from the candidate item before you get to a shared ancestor with the unique text.

<tt>And '''I set the field "field name" to "text value" in the app'''</tt>

This sets a text field to the given value. For the field name, you can use the placeholder text (exact match will be found first, otherwise partial match if any).

This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.

* The normal version of this step supports various form fields, but in the app this only supports text fields at the moment. Use the press step (above) for other types of field.
* When used with a rich-text editor, you can include HTML tags in the value if necessary.

<tt>And '''I press the back button in the app'''</tt>

<tt>And '''I press the main menu button in the app'''</tt>

<tt>And '''I press the page menu button in the app'''</tt>

These steps will press, respectively:

* The back button (the left pointing arrow at top left of the app).
* The main menu button (the '...' icon at bottom right of the app).
* The page menu button, if present (the '...' icon at top right of the app).

Note that both the main menu and page menu use a 'more' icon so they are annoying to activate with the generic press command.

<tt>And I switch to the browser tab opened by the app</tt>

<tt>And I close the browser tab opened by the app</tt>

These two steps are necessary if you want to test the transition between the app and browser (e.g. test 'Open in browser' links). For example, after pressing 'Open in browser' you can use the first step above, and then you will be able to use normal Moodle Behat steps to check the browser tab. Then when finished, use the second step above.

=== Tests ===

<tt>Then '''the header should be "Course 1" in the app'''</tt>

This checks the text of the current page header (orange stripe at top of page) in the app. It must be an exact match for the specified text.

For this scenario, <tt>I should see</tt> would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.

=== Standard test steps ===

You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don't work very well. The app has a complex DOM and previous pages that are 'back' from your current page may still be present in the DOM, which means that any steps that just look for the first matching element in the DOM are likely to look for elements on a page you're not even on.

==== Useful, working steps ====

* <tt>I should see</tt> and <tt>I should not see</tt> are very useful for checking results.
* <tt>I change viewport size to "360x640"</tt> is a useful background step if you want your tests to run in mobile phone (rather than tablet/desktop) format. You can also use this step mid-test to simulate switching between portrait and landscape formats.
* <tt>I pause</tt> works and is very useful to debug your scenario.

==== Problematic steps ====

* The <tt>I reload the page</tt> step does not work correctly in the app and may leave your test in a mess. Use <tt>I enter the app</tt> if you want to reload the app.

=== Leaving the app ===

If you want to leave the app and go back to Moodle within a scenario, simply use a Moodle step that goes to a page, such as <tt>I am on site homepage</tt> or <tt>I am on "Course 1" course homepage</tt>.

You only need to do this if you want to carry out actions within Moodle after using the app, within the scenario. At the end of your scenario, there is no need to explicitly leave the app; Moodle will automatically start the next scenario on the Moodle start page as usual.

== Limitations ==

These limitations apply to the current system and can be resolved:

* There is no obvious way to attach files.

These limitations are (at least currently) fundamental to the testing approach:

* It is not possible to test behaviour specific to iOS, because tests run in Chrome. (Most iOS-specific failures are caused by problems with the Safari browser used on iOS, which isn't very good.)
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.

It's my firm belief that even given those restrictions on test coverage, being able to run Behat tests is massively beneficial compared to having to test everything by hand for every app release.

== Advanced ==

=== Versioning ===

The Behat tests are stored in the Moodle codebase, so they always relate to a particular Moodle version, but sometimes it might be necessary to have different tests for different versions of the mobile app. For example, you may be writing a test in Moodle 3.6, where the behaviour in the Moodle 3.6 app is different from behaviour in the Moodle 3.7 app (but both apps can connect to the server).

For these situations:

* In addition to the @app tag, add a version-specific tag to your scenario or feature.
* There are two types of tag: '''@app_from3.7''' (include for every app version from 3.7 and newer) or '''@app_upto3.6.3''' (include for every app version up to 3.6.3, but not after that).
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).

=== Testing against multiple app versions ===

If you need to run tests against multiple versions of the mobile app, you can do this in two ways:

# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.
# Maintain multiple copies of the mobile app workspace and switch between them by changing config.php. Then re-run Behat init and run the Behat tests again.

In both cases, because you need to run Behat init and change the Behat configuration, you cannot do this in parallel; if you want to run these tests in parallel you will also need separate Moodle installations with their own config.php, wwwroot, and dataroot.