MoodleDocs - User contributions [en]

Process

2020-02-09T15:58:29Z

TimHunt: /* Submit the code for integration */

This document summarises the various development processes used in developing Moodle. There are four main processes that overlap.

==Integration workflow in the tracker==

The Moodle tracker keeps track of the status of all bug fixes and new features.

We use a workflow that ensures that new code receives multiple reviews by different people before it is included into the core Moodle code.

[[Image:Workflow.jpg]]

A number of roles make this work:

===Users===

Users report bugs and make feature requests directly in the tracker, by creating new issues with a summary and a description.

===Developers===

Developers work on the issues in the tracker to specify solutions and write code that implements these solutions. They will often ask other developers to "peer review" their code in the early stages to avoid problems later on.

While many of the developers work for Moodle.com, a large number are part of the global development community around Moodle. If you're interested in becoming a recognised developer, see [[Tracker_guide#Tracker_groups_and_permissions|Tracker groups and permissions]].

===CiBoT===

CiBoT is not a person but a bot who monitors the tracker and performs the [[Automated code review]] when issue is submitted for Peer review or when developer added ''cime'' label.

===Component leads===

[https://tracker.moodle.org/projects/MDL?selectedItem=com.atlassian.jira.jira-projects-plugin:components-page Component leads] are developers with some responsibility for particular components (plugins or modules) in Moodle. They have authority to decide that a particular fix is suitable and complete enough to be considered for integration in Moodle core and should be called upon to complete peer reviews for code in their components. Note that, apart from that, every component also has some [[Component Leads|HQ Component leads]] that will specifically work on associated issues, triaging, monitoring, reviewing, fixing them.

===Integrators===

On Monday and Tuesday of each week, the integration team (a small team of senior developers employed by Moodle HQ) conducts a code-level review of all issues in the integration queue. This is often called the "pull" process. If the fix is judged appropriate they will integrate the code into our git integration repository for further testing and it gets added to the testing queue.

If they find problems they reject the issue and send it back to the developer for further work.

===Testers===

On Wednesday each week, testers look at all the issues in the testing queue, trying each fix and feature to make sure that it does actually fix the problem it was supposed to, and that there are no regressions.

If they find problems they reject the issue and integrators may remove it from the integration repository and push it back to the developer for further work.

See [[Testing of integrated issues]] for more details.

===Production maintainers===

On Thursday each week, production maintainers merge all the issues that passed testing into the git production repository, and it becomes available for use on production systems via git and download packages.

==Stable maintenance cycles==

Moodle releases regular updates of the stable version of the software to fix bugs and other issues. Releases like 2.2.1, 2.2.2, 2.2.3 etc only include fixes based on the latest major release (2.2) and never any significant new features or database changes.

At Moodle HQ there are teams of developers using the [http://www.scrum.org/ Scrum framework] to work on these issues (as well as new features for [[#Major_release_cycles|major releases]]).

===Minor release (point release) timing===

After [[#Major_release_cycles|major releases]] there will be minor releases.
* x.x.1 will occur approximately two months after each major release (eg. 2.x).
* There will then be another point release every two months after that.

See the [[Releases#General_release_calendar|General release calendar]] for details.

===Issue triage===

[[Bug_triage|Issue triage]] involves evaluating new issues, making sure that they are recorded correctly. One of the most important jobs triagers do is to identify issues that should be fixed in the stable branch. These are set with a priority ranging from "Trivial" up to "Blocker" and other features are checked.

At Moodle HQ there are currently teams working on stable issues (mostly bugs reported by users) and improvements and new features (Partners, Moodle Association, user suggestions and Martin Dougiamas).

===Scrum===

At Moodle HQ, every three weeks, the stable team takes a number of the most urgent issues from the backlog to work on during a period known as a ''sprint''.

At the start of a sprint there is a period of planning and estimation. All issues on the backlog are given a relative rank that is based on issue features including priority, security, Partner interest, patches and votes. Issues are given a relative size in Story Points and these points are summed to allow the teams to determine how many issues they can work on in the sprint.

During the sprint, the team meets daily to discuss solutions and progress, as well as to organise testing and peer reviews of code. The team has a ''Scrum master'' to help everyone stay organised, to "unblock" any barriers to progress and to protect the team from distracting influences (mostly people attempting to add to the developers' workloads) during the sprint. The teams' work is documented publicly in the tracker.

Whenever a solution for an issue is finished, it is submitted to the standard integration workflow process described above.

==Major release cycles==

Since Moodle 2.0, we have a policy of release major versions (eg 2.1, 2.2) every six months in May and November. See the [[Releases#General_release_calendar|General release calendar]] for more details.

Each release can be different, but generally the cycles work as follows.

===Define roadmap===

The product owner (Martin Dougiamas) defines the likely roadmap based on community wishes, third-party developments and important issues within the existing code.

Sometimes new features might be based on earlier features, sometimes they may be something developed by a third party that needs to be evaluated and sometimes it might be something completely new.

===Planning and development===

The UX team, employed at Moodle HQ, work on specifications of major new features throughout the cycle, specifying project ahead of development time.

New features are worked on by the "Dev" team. The process of [[#New_feature_development|new feature development]] is described below. When specifications are in place, new code is developed during sprints and goes through the standard weekly integration workflow described above.

===Testing===

During development, as new code is integrated, automated testing conducted at the [[PHPUnit|code]] and [[Acceptance_testing|interface]] levels, to make sure there are no regressions caused by new features.

In the last month before the release, a feature freeze is called (no new features can be added) and volunteer testers from the Moodle community perform manual QA testing of Moodle features. The current set of functional tests is listed in MDLQA-1. The list of tests is extended as new features are added, though we're also trying to reduce the number as more automated [[Acceptance_testing|acceptance tests]] are developed.

There is also a set of tests for manually testing any major theme changes - MDLQA-11592.

For more details, see [[Testing]].

===Sprints===

At Moodle HQ, development takes place in sprints. The sprints are three-week periods during which developers to focus on a fixed list of issues. Sprints are arranged within each release cycle as shown in the diagram below.

===Events during cycle===

During each cycle there are a periods and events that occur between and around sprints.

[[Image:Dev sprint calendar.png|800px]]

; '''Planning and bug fixing'''
: A period during which the Roadmap is explored, specs are written and prototypes are created. Regressions in the recent release are fixed as they arise.
; '''End sync period'''
: During the [[Integration Review#On-sync period|on-sync period]], the recent release and master versions are kept synchronised. No new code is added during this period, which ensures regressions are fixed rapidly. This also allows for planning and provides relief for developers after a release.
; '''Personal projects'''
: Affecting full-time HQ developers only, this period allows for individual creations to be explored and provides a break from sprints.
; '''Code freeze'''
: A point after which no new code (only fixes to existing code) is accepted until beyond the release. This stabilisation allows for QA testing.
; '''QA, bug fixing, continuous integration'''
: A period after the code freeze where quality assurance testing takes place. No new code is added, which means developers are able to respond rapidly to bugs found. Integration becomes [[Integration Review#During continuous integration/Freeze/QA period|continuous]], meaning that failed QA tests can be re-run within days rather than having to wait for the weekly release.
; '''Release candidate'''
: A point prior to the full release where a candidate is made public for wider testing.

==New feature development==

Major new features in Moodle usually should go through the following process.

===Specification===

The User Experience (UX) team should create detailed wireframes and features and goals for the new feature. It should be agreed upon and as final as possible before development starts.

Developers should create a detailed spec (here in the developer docs) outlining their goals for the development and their design for meeting those goals. The more detail the better.

Developers should also create an issue in the tracker (linking to your docs) to keep track of the project status.

===Community consultation===

Get the community involved in looking at the spec to see if it meets their needs and to get further feedback. Please post in the [http://moodle.org/mod/forum/view.php?id=8052 Future major features forum] on moodle.org. You could also blog/tweet about it etc.

Community developers proposing a new feature will want to talk with HQ core developers to make sure the ideas make sense, and possibly get some review on database design, architecture and so on.

===Develop the code using Git===

Develop your code on an open Git repository, like github.com. That enables people to see your code and to help you as it develops. Testers and early adopters also have the opportunity to try it early in the process and give you more valuable feedback.

Coverage with automated tests ([[PHPUnit]] or [[Behat|Behat_integration]]) is mandatory for new features.

It is essential that your code follows the [[Coding|Moodle Coding Guide]].

===Submit your code for peer review===

Click on "Request peer review" button in the tracker.

You need to fill in the information about your public git repository and which branches the fixes are on. Make sure you are listed as Assignee.

This would be a good time to fill in the testing instructions (read the [[Testing instructions guide|instructions guide]]) for how to verify your fix is correct. You may also wish to add a comment in the bug.

Component leads should put issues, which affect code in their components, up for peer review to allow interested parties to provide feedback. However, if it is not reviewed in a week, a component lead may send the issue to integration. If integrators consider that the issue has not been given proper chance for peer review (e.g. is extremely large or complex...) it can be decided to move the issue back in the process.

All other developers, including people who are component leads but working outside their component, should have their issues peer reviewed before they are sent to integration.

===Peer review===

The [http://tracker.moodle.org/browse/MDL#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel component lead] should peer-review the change. If there is no component lead for an affected component, any other recognised developer may complete the peer review. The peer reviewer will either give you comments on the code and if it needs more work.

Process and the list of things to check are described in [[Peer reviewing]].

===Submit the code for integration===

The developer is responsible for acting on the feedback from the peer reviewer. If changes have been made and the developer is satisfied that this has accommodated the feedback from the peer reviewer, then the developer can submit the issue for integration. If there have been significant changes after the peer review, or if the peer reviewer has raised concerns about the approach taken, then the developer should offer the issue up for peer review again, most often to the same peer reviewer, but not necessarily.

Submitting an issue to integration is much the same as for any Moodle code. See [[Integration Review]] and the information about the integration workflow above.

==Fixing a bug==

Bug fixes, and minor features or enhancements should go through the following process. (The only exception is English language string typo fixes or suggested improvements, which may be contributed to the en_fix language pack on the [http://lang.moodle.org/ Moodle translation site].)

===Make sure there is a tracker issue===

Every change must have an issue in the tracker. If you are fixing a bug, there is probably one there already, but if not, create one. [[Tracker tips|Tips for searching tracker]].

===Decide which branches the fix is required on===

Bugs should normally be fixed on all the supported stable branches that are affected. New features should just go into master, but sometimes minor enhancements are made on the most recent stable branch.

===Develop your change using git===

Develop your fix and push the change to an open git repository, for example on github.com. See also [[Git for developers]]

It is essential that your code follows the [[Coding|Moodle Coding Guide]].

You will need to push one commit for each branch the fix needs to be applied to. Often people use branch names like MDL-12345-31_brief_name so it is clear what each branch is. [http://kernel.org/pub/software/scm/git/docs/git-cherry-pick.html git cherry-pick] can help with replicating the fix onto different branches.

===Submit your code for peer review===

Once your fix is done, it should be submitted for a peer review.

The following information is necessary for this:
* Information about your public git repository
** repository URL
** branch name(s)
** diff URL
* [[Testing instructions guide|Testing instructions]] for how to verify your fix is correct.

If you have never contributed to Moodle and don't see a button "Request peer review", just comment on the issue with the above information. The component lead or another user with sufficient privileges will then send the issue up for peer review for you.

After your first fix is integrated you will be added to developers group and will be able to send issues for peer review yourself. In this case make sure you are listed as Assignee and click on "Request peer review" button in the tracker

===Peer review===

The [https://tracker.moodle.org/projects/MDL?selectedItem=com.atlassian.jira.jira-projects-plugin:components-page component lead] should peer-review the change. If there is no component lead for an affected component, any other recognised developer may complete the peer review. The peer reviewer will either give you comments on the code and if it needs more work.

Process and the list of things to check are described in [[Peer reviewing]].

===Submit your code for integration===

It will then be reviewed the following week by one of the integration team and either integrated or rejected. Once integrated, the fix will be tested, and then included in the next weekly release. For details see [[Integration Review]].

==Security issues==

Issues identified as [[Security|security issues]] are resolved in a slightly different way, in order to achieve responsible disclosure as described in [[Moodle security procedures]].

* Security issues should be labelled as "Minor" or "Serious" in order control visibility of the issue.
** An issue reported with a security level of "Could be a security issue" should be evaluated as soon as possible and either set as "Minor" or "Serious" or the security level should be set to "None".
* Solutions to security issues should not:
** be made available in public repositories.
*** If a developer has shared a solution as Git branches via Github, they should be asked to provide the solutions as [[How_to_create_a_patch|stand-alone patches]] attached to the issue and to [[#How to remove a branch from Github|remove the solution from Github]].
** contain details about the security problem in the commit message.
*** Instead use generic terms like, "improve", "better handling of" ..
* The solution will not be integrated until the week before a [[Process#Stable_maintenance_cycles|minor release]] following the normal [[Release process|Release process]]. In short, the issue will be incorporated into the integration version, rebased, tested and made ready for release as a normal issue would, but not until as late as possible.
* Details of security issues will be shared with registered admins with the minor release.
* Details of security issues will not be publicly announced until one week after a minor release to allow admins to update.

Note that not all the labelled (minor) security issues are always handled following the procedure above. It's possible that, after discussion, it's decided a given issue is not a real Moodle security problem (say external disclosures/potential attacks using Moodle as vector, not as target, discussions revealing some private details...). Those issues will be processed as normal issues, generating the needed user documentation if necessary and will be part of the habitual weekly releases.

====How to remove a branch from Github====

To remove a branch from Github, you can use the following command.

git push github :remote_branch

Where ''remote_branch'' is the name of your remote branch, for example 'wip-mdl-1234'. This effectively replaces the remote branch with nothing, removing the remote branch, but leaving the branch intact in your local Git repository. Please note that its likely that your commit will still exist on github due to the nature of git, so its best to avoid doing this in the first place.

==Policy issues==

Occasionally within Moodle we run into policy issues where a high-level decision needs to be made about how things are to be done.

In these cases the process is as follows:
* Create an issue in the tracker with a [https://tracker.moodle.org/browse/MDL/component/12733 Policy component] and put "POLICY:" as a prefix on the summary.
* In the description describe the problem clearly as well as all the options. If it's long then make a page here in Moodle Dev Docs and link to it.
* Do not use this issue for code. If there are issues that depend on this policy decision, then add tracker links to them as dependencies.
* Feel free to encourage people to come and talk about the policy to support various points of view. The more evidence we have (from everyone in the community) the better.

Some time has been scheduled in the weekly Moodle HQ meeting to look at Policy issues and try to make decisions on them. We discuss all the evidence and try to achieve a high amount of consensus. Deadlocked issues can be resolved by a decision from Martin Dougiamas (this is rarely needed).

Decisions will be posted on the issue and that issue will be closed, allowing any dependent issues to continue to integration (or not). Decisions are final and bribes hardly ever work.

==See also==

* [[Release process]]
* [[Deprecation]]
* [http://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11350 Integration dashboard]

Walks-though of the process for contributors:
* By Dan Poltawski, Integrator: http://www.slideshare.net/poltawski/how-to-guarantee-your-change-is-integrated-to-moodle-core, https://www.youtube.com/watch?v=836WtnM2YpM
* By Tim Hunt, contributor: http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html and https://www.youtube.com/watch?v=gPPA3h7OGQU

[[Category:Processes]]
[[Category:Quality Assurance]]
[[Category:Git]]
[[Category:Core development]]

Process

2020-02-09T15:58:00Z

TimHunt: /* Submit your code for integration */

This document summarises the various development processes used in developing Moodle. There are four main processes that overlap.

==Integration workflow in the tracker==

The Moodle tracker keeps track of the status of all bug fixes and new features.

We use a workflow that ensures that new code receives multiple reviews by different people before it is included into the core Moodle code.

[[Image:Workflow.jpg]]

A number of roles make this work:

===Users===

Users report bugs and make feature requests directly in the tracker, by creating new issues with a summary and a description.

===Developers===

Developers work on the issues in the tracker to specify solutions and write code that implements these solutions. They will often ask other developers to "peer review" their code in the early stages to avoid problems later on.

While many of the developers work for Moodle.com, a large number are part of the global development community around Moodle. If you're interested in becoming a recognised developer, see [[Tracker_guide#Tracker_groups_and_permissions|Tracker groups and permissions]].

===CiBoT===

CiBoT is not a person but a bot who monitors the tracker and performs the [[Automated code review]] when issue is submitted for Peer review or when developer added ''cime'' label.

===Component leads===

[https://tracker.moodle.org/projects/MDL?selectedItem=com.atlassian.jira.jira-projects-plugin:components-page Component leads] are developers with some responsibility for particular components (plugins or modules) in Moodle. They have authority to decide that a particular fix is suitable and complete enough to be considered for integration in Moodle core and should be called upon to complete peer reviews for code in their components. Note that, apart from that, every component also has some [[Component Leads|HQ Component leads]] that will specifically work on associated issues, triaging, monitoring, reviewing, fixing them.

===Integrators===

On Monday and Tuesday of each week, the integration team (a small team of senior developers employed by Moodle HQ) conducts a code-level review of all issues in the integration queue. This is often called the "pull" process. If the fix is judged appropriate they will integrate the code into our git integration repository for further testing and it gets added to the testing queue.

If they find problems they reject the issue and send it back to the developer for further work.

===Testers===

On Wednesday each week, testers look at all the issues in the testing queue, trying each fix and feature to make sure that it does actually fix the problem it was supposed to, and that there are no regressions.

If they find problems they reject the issue and integrators may remove it from the integration repository and push it back to the developer for further work.

See [[Testing of integrated issues]] for more details.

===Production maintainers===

On Thursday each week, production maintainers merge all the issues that passed testing into the git production repository, and it becomes available for use on production systems via git and download packages.

==Stable maintenance cycles==

Moodle releases regular updates of the stable version of the software to fix bugs and other issues. Releases like 2.2.1, 2.2.2, 2.2.3 etc only include fixes based on the latest major release (2.2) and never any significant new features or database changes.

At Moodle HQ there are teams of developers using the [http://www.scrum.org/ Scrum framework] to work on these issues (as well as new features for [[#Major_release_cycles|major releases]]).

===Minor release (point release) timing===

After [[#Major_release_cycles|major releases]] there will be minor releases.
* x.x.1 will occur approximately two months after each major release (eg. 2.x).
* There will then be another point release every two months after that.

See the [[Releases#General_release_calendar|General release calendar]] for details.

===Issue triage===

[[Bug_triage|Issue triage]] involves evaluating new issues, making sure that they are recorded correctly. One of the most important jobs triagers do is to identify issues that should be fixed in the stable branch. These are set with a priority ranging from "Trivial" up to "Blocker" and other features are checked.

At Moodle HQ there are currently teams working on stable issues (mostly bugs reported by users) and improvements and new features (Partners, Moodle Association, user suggestions and Martin Dougiamas).

===Scrum===

At Moodle HQ, every three weeks, the stable team takes a number of the most urgent issues from the backlog to work on during a period known as a ''sprint''.

At the start of a sprint there is a period of planning and estimation. All issues on the backlog are given a relative rank that is based on issue features including priority, security, Partner interest, patches and votes. Issues are given a relative size in Story Points and these points are summed to allow the teams to determine how many issues they can work on in the sprint.

During the sprint, the team meets daily to discuss solutions and progress, as well as to organise testing and peer reviews of code. The team has a ''Scrum master'' to help everyone stay organised, to "unblock" any barriers to progress and to protect the team from distracting influences (mostly people attempting to add to the developers' workloads) during the sprint. The teams' work is documented publicly in the tracker.

Whenever a solution for an issue is finished, it is submitted to the standard integration workflow process described above.

==Major release cycles==

Since Moodle 2.0, we have a policy of release major versions (eg 2.1, 2.2) every six months in May and November. See the [[Releases#General_release_calendar|General release calendar]] for more details.

Each release can be different, but generally the cycles work as follows.

===Define roadmap===

The product owner (Martin Dougiamas) defines the likely roadmap based on community wishes, third-party developments and important issues within the existing code.

Sometimes new features might be based on earlier features, sometimes they may be something developed by a third party that needs to be evaluated and sometimes it might be something completely new.

===Planning and development===

The UX team, employed at Moodle HQ, work on specifications of major new features throughout the cycle, specifying project ahead of development time.

New features are worked on by the "Dev" team. The process of [[#New_feature_development|new feature development]] is described below. When specifications are in place, new code is developed during sprints and goes through the standard weekly integration workflow described above.

===Testing===

During development, as new code is integrated, automated testing conducted at the [[PHPUnit|code]] and [[Acceptance_testing|interface]] levels, to make sure there are no regressions caused by new features.

In the last month before the release, a feature freeze is called (no new features can be added) and volunteer testers from the Moodle community perform manual QA testing of Moodle features. The current set of functional tests is listed in MDLQA-1. The list of tests is extended as new features are added, though we're also trying to reduce the number as more automated [[Acceptance_testing|acceptance tests]] are developed.

There is also a set of tests for manually testing any major theme changes - MDLQA-11592.

For more details, see [[Testing]].

===Sprints===

At Moodle HQ, development takes place in sprints. The sprints are three-week periods during which developers to focus on a fixed list of issues. Sprints are arranged within each release cycle as shown in the diagram below.

===Events during cycle===

During each cycle there are a periods and events that occur between and around sprints.

[[Image:Dev sprint calendar.png|800px]]

; '''Planning and bug fixing'''
: A period during which the Roadmap is explored, specs are written and prototypes are created. Regressions in the recent release are fixed as they arise.
; '''End sync period'''
: During the [[Integration Review#On-sync period|on-sync period]], the recent release and master versions are kept synchronised. No new code is added during this period, which ensures regressions are fixed rapidly. This also allows for planning and provides relief for developers after a release.
; '''Personal projects'''
: Affecting full-time HQ developers only, this period allows for individual creations to be explored and provides a break from sprints.
; '''Code freeze'''
: A point after which no new code (only fixes to existing code) is accepted until beyond the release. This stabilisation allows for QA testing.
; '''QA, bug fixing, continuous integration'''
: A period after the code freeze where quality assurance testing takes place. No new code is added, which means developers are able to respond rapidly to bugs found. Integration becomes [[Integration Review#During continuous integration/Freeze/QA period|continuous]], meaning that failed QA tests can be re-run within days rather than having to wait for the weekly release.
; '''Release candidate'''
: A point prior to the full release where a candidate is made public for wider testing.

==New feature development==

Major new features in Moodle usually should go through the following process.

===Specification===

The User Experience (UX) team should create detailed wireframes and features and goals for the new feature. It should be agreed upon and as final as possible before development starts.

Developers should create a detailed spec (here in the developer docs) outlining their goals for the development and their design for meeting those goals. The more detail the better.

Developers should also create an issue in the tracker (linking to your docs) to keep track of the project status.

===Community consultation===

Get the community involved in looking at the spec to see if it meets their needs and to get further feedback. Please post in the [http://moodle.org/mod/forum/view.php?id=8052 Future major features forum] on moodle.org. You could also blog/tweet about it etc.

Community developers proposing a new feature will want to talk with HQ core developers to make sure the ideas make sense, and possibly get some review on database design, architecture and so on.

===Develop the code using Git===

Develop your code on an open Git repository, like github.com. That enables people to see your code and to help you as it develops. Testers and early adopters also have the opportunity to try it early in the process and give you more valuable feedback.

Coverage with automated tests ([[PHPUnit]] or [[Behat|Behat_integration]]) is mandatory for new features.

It is essential that your code follows the [[Coding|Moodle Coding Guide]].

===Submit your code for peer review===

Click on "Request peer review" button in the tracker.

You need to fill in the information about your public git repository and which branches the fixes are on. Make sure you are listed as Assignee.

This would be a good time to fill in the testing instructions (read the [[Testing instructions guide|instructions guide]]) for how to verify your fix is correct. You may also wish to add a comment in the bug.

Component leads should put issues, which affect code in their components, up for peer review to allow interested parties to provide feedback. However, if it is not reviewed in a week, a component lead may send the issue to integration. If integrators consider that the issue has not been given proper chance for peer review (e.g. is extremely large or complex...) it can be decided to move the issue back in the process.

All other developers, including people who are component leads but working outside their component, should have their issues peer reviewed before they are sent to integration.

===Peer review===

The [http://tracker.moodle.org/browse/MDL#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel component lead] should peer-review the change. If there is no component lead for an affected component, any other recognised developer may complete the peer review. The peer reviewer will either give you comments on the code and if it needs more work.

Process and the list of things to check are described in [[Peer reviewing]].

===Submit the code for integration===

The developer is responsible for acting on the feedback from the peer reviewer. If changes have been made and the developer is satisfied that this has accommodated the feedback from the peer reviewer, then the developer can submit the issue for integration. If there have been significant changes after the peer review, or if the peer reviewer has raised concerns about the approach taken, then the developer should offer the issue up for peer review again, most often to the same peer reviewer, but not necessarily.

Submitting an issue to integration is much the same as for any Moodle code. See the information about the integration workflow above.

==Fixing a bug==

Bug fixes, and minor features or enhancements should go through the following process. (The only exception is English language string typo fixes or suggested improvements, which may be contributed to the en_fix language pack on the [http://lang.moodle.org/ Moodle translation site].)

===Make sure there is a tracker issue===

Every change must have an issue in the tracker. If you are fixing a bug, there is probably one there already, but if not, create one. [[Tracker tips|Tips for searching tracker]].

===Decide which branches the fix is required on===

Bugs should normally be fixed on all the supported stable branches that are affected. New features should just go into master, but sometimes minor enhancements are made on the most recent stable branch.

===Develop your change using git===

Develop your fix and push the change to an open git repository, for example on github.com. See also [[Git for developers]]

It is essential that your code follows the [[Coding|Moodle Coding Guide]].

You will need to push one commit for each branch the fix needs to be applied to. Often people use branch names like MDL-12345-31_brief_name so it is clear what each branch is. [http://kernel.org/pub/software/scm/git/docs/git-cherry-pick.html git cherry-pick] can help with replicating the fix onto different branches.

===Submit your code for peer review===

Once your fix is done, it should be submitted for a peer review.

The following information is necessary for this:
* Information about your public git repository
** repository URL
** branch name(s)
** diff URL
* [[Testing instructions guide|Testing instructions]] for how to verify your fix is correct.

If you have never contributed to Moodle and don't see a button "Request peer review", just comment on the issue with the above information. The component lead or another user with sufficient privileges will then send the issue up for peer review for you.

After your first fix is integrated you will be added to developers group and will be able to send issues for peer review yourself. In this case make sure you are listed as Assignee and click on "Request peer review" button in the tracker

===Peer review===

The [https://tracker.moodle.org/projects/MDL?selectedItem=com.atlassian.jira.jira-projects-plugin:components-page component lead] should peer-review the change. If there is no component lead for an affected component, any other recognised developer may complete the peer review. The peer reviewer will either give you comments on the code and if it needs more work.

Process and the list of things to check are described in [[Peer reviewing]].

===Submit your code for integration===

It will then be reviewed the following week by one of the integration team and either integrated or rejected. Once integrated, the fix will be tested, and then included in the next weekly release. For details see [[Integration Review]].

==Security issues==

Issues identified as [[Security|security issues]] are resolved in a slightly different way, in order to achieve responsible disclosure as described in [[Moodle security procedures]].

* Security issues should be labelled as "Minor" or "Serious" in order control visibility of the issue.
** An issue reported with a security level of "Could be a security issue" should be evaluated as soon as possible and either set as "Minor" or "Serious" or the security level should be set to "None".
* Solutions to security issues should not:
** be made available in public repositories.
*** If a developer has shared a solution as Git branches via Github, they should be asked to provide the solutions as [[How_to_create_a_patch|stand-alone patches]] attached to the issue and to [[#How to remove a branch from Github|remove the solution from Github]].
** contain details about the security problem in the commit message.
*** Instead use generic terms like, "improve", "better handling of" ..
* The solution will not be integrated until the week before a [[Process#Stable_maintenance_cycles|minor release]] following the normal [[Release process|Release process]]. In short, the issue will be incorporated into the integration version, rebased, tested and made ready for release as a normal issue would, but not until as late as possible.
* Details of security issues will be shared with registered admins with the minor release.
* Details of security issues will not be publicly announced until one week after a minor release to allow admins to update.

Note that not all the labelled (minor) security issues are always handled following the procedure above. It's possible that, after discussion, it's decided a given issue is not a real Moodle security problem (say external disclosures/potential attacks using Moodle as vector, not as target, discussions revealing some private details...). Those issues will be processed as normal issues, generating the needed user documentation if necessary and will be part of the habitual weekly releases.

====How to remove a branch from Github====

To remove a branch from Github, you can use the following command.

git push github :remote_branch

Where ''remote_branch'' is the name of your remote branch, for example 'wip-mdl-1234'. This effectively replaces the remote branch with nothing, removing the remote branch, but leaving the branch intact in your local Git repository. Please note that its likely that your commit will still exist on github due to the nature of git, so its best to avoid doing this in the first place.

==Policy issues==

Occasionally within Moodle we run into policy issues where a high-level decision needs to be made about how things are to be done.

In these cases the process is as follows:
* Create an issue in the tracker with a [https://tracker.moodle.org/browse/MDL/component/12733 Policy component] and put "POLICY:" as a prefix on the summary.
* In the description describe the problem clearly as well as all the options. If it's long then make a page here in Moodle Dev Docs and link to it.
* Do not use this issue for code. If there are issues that depend on this policy decision, then add tracker links to them as dependencies.
* Feel free to encourage people to come and talk about the policy to support various points of view. The more evidence we have (from everyone in the community) the better.

Some time has been scheduled in the weekly Moodle HQ meeting to look at Policy issues and try to make decisions on them. We discuss all the evidence and try to achieve a high amount of consensus. Deadlocked issues can be resolved by a decision from Martin Dougiamas (this is rarely needed).

Decisions will be posted on the issue and that issue will be closed, allowing any dependent issues to continue to integration (or not). Decisions are final and bribes hardly ever work.

==See also==

* [[Release process]]
* [[Deprecation]]
* [http://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11350 Integration dashboard]

Walks-though of the process for contributors:
* By Dan Poltawski, Integrator: http://www.slideshare.net/poltawski/how-to-guarantee-your-change-is-integrated-to-moodle-core, https://www.youtube.com/watch?v=836WtnM2YpM
* By Tim Hunt, contributor: http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html and https://www.youtube.com/watch?v=gPPA3h7OGQU

[[Category:Processes]]
[[Category:Quality Assurance]]
[[Category:Git]]
[[Category:Core development]]

Activity chooser

2019-11-15T07:48:36Z

TimHunt: /* Adding activity items to the chooser through plugins */

{{Infobox Project
|state = Open
|name = Activity chooser
|tracker = MDL-67255 (epic), MDL-57828, MDL-61511
|discussion = https://moodle.org/mod/forum/discuss.php?d=346664
|assignee = Team Alpha
}}

== Introduction ==

Through our road-map creation process of looking at highly voted tracker issues and relevant forum posts, as well as MUA interaction, an update to the activity chooser to simplify and make less intimidating, was chosen.

MDL-57828 was created and worked on, but unfortunately stalled, and did not complete its way through the integration process. There is a substantial forum post [https://moodle.org/mod/forum/discuss.php?d=346664], with many suggestions and current pain points with the activity chooser. The MUA created a proposal issue (MDL-61511) to tackle the same issue.

We have recently been analysing how course creation is achieved. Two main ideas were tested with focus groups to try and find the best away to approach course creation. With this information we are confident that we have a user focused design that will improve the activity chooser for everyone.

We would like to invite everyone to express their opinion on this improvement. Course creation is a Moodle activity that is fundamental to teaching a course online, and we would like to ensure that the process is as easy and intuitive as possible.

== Features ==

The following are changes that we are planning on making in this project. We have a demo that can be viewed and interacted with.
[https://projects.invisionapp.com/share/SVSREPYNBYG#/screens/388682478 Invisio mockup of the activity chooser].

=== Larger display area ===

The activity chooser will be wider and have the activities in a grid format. This allows for more activities to be seen at once.

=== Activities and resources are now merged ===

Our research found that the distinction been activities and resources was not useful to teachers and so now these two categories have been merged together.

=== Starred / Favourites tab ===

The user can now select activities to be added to the Starred tab. The starred tab is shown by default to users when pulling up the activity chooser.

[[File:activity-chooser-starred.png|The starred tab]]

=== Recommended tab ===

Site administrators will now be able to set a selection of activities as recommended. These recommended activities will show up in a tab in the activity chooser for the course creator to view. If no recommendations are made then this tab will not be displayed.

[[File:activity-chooser-recommend.png|The recommended tab]]

=== H5P activities included ===

We are looking at adding the ability for users to select an H5P activity from the activity chooser.

=== Smart search bar ===

To help find activities from the activity chooser, we will be adding a search bar, that will search through both the names of the activities, and also the information text, to try and find relevant activities that the user may want.

=== Other activity types ===

Other activity types such as LTI will be able to be added to the activity chooser for the user to select.

=== Activity information hidden ===

The information about an activity will be accessible through the 'i' icon. Clicking the link will show additional information about the activity. This will free up space for other activities to be shown rather than always taking up half of the activity chooser.

[[File:activity-chooser-info.png|Additional information about an activity]]

=== Adding activity items to the chooser through plugins ===

It is currently possible to include additional items to the activity picker (such as the external tools). We are looking at expanding this to allow any plugin to add items to the activity picker.

''What do you mean by this? I can see it makes sense for mod_ plugins to be able to do this, but why any plugin type? Can you give an example that shows why this is a requirement. Thanks. --Tim.''

Moodle 3.8 release notes

2019-11-13T23:33:13Z

TimHunt:

[[Releases]] > {{FULLPAGENAME}}

Release date: Not yet released - scheduled for 18 November 2019

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.8%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.8].

If you are upgrading from a previous version, please see [[:en:Upgrading|Upgrading]] in the user docs.

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software and operating systems up-to-date.

* Moodle upgrade: Moodle 3.2 or later
* PHP version: minimum PHP 7.1.0 ''Note: minimum PHP version has increased since Moodle 3.6''. PHP 7.2.x and 7.3.x are supported too. PHP 7.x could have some [https://docs.moodle.org/dev/Moodle_and_PHP7#Can_I_use_PHP7_yet.3F engine limitations].
* PHP extension '''intl''' is required since Moodle 3.4 (it was recommended in 2.0 onwards)

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.4
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.6
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 5.5.31
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2012 ''(increased since Moodle 3.7)''
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 11.2
| Latest
|}

==Client requirements==

=== Browser support ===
Moodle is compatible with any standards compliant web browser. We regularly test Moodle with the following browsers:

Desktop:
* Chrome
* Firefox
* Safari
* Edge
* Internet Explorer

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date.

Note: Legacy browsers with known compatibility issues with Moodle 3.5:
* Internet Explorer 10 and below
* Safari 7 and below

==Major features==

===Analytics===

* MDL-64739 - Analytics models may be restricted to category or course contexts
* MDL-65588 - Insights about students who have not logged in recently
* MDL-65562 - Report on the actions executed by users on predictions
* MDL-65633 - Allow targets to limit the analysis interval to a specific interface or parent class.
* MDL-66234 - Extra garbage collection for analytics
* MDL-66254 - Require enrolments to be active for most of the analysis interval
* MDL-62191 - Add bulk actions for analytics' insights
* MDL-66536 - Insight notifications improvements
* MDL-60949 - Analytics models should be sorted by name and not last modified
* MDL-66004 - Allow the Python machine learning backend to run from a separate server

===Forum summary report===

* MDL-66298 - Forum summary report option to message selected users
* MDL-66153 - Forum report: Basic skeleton
* MDL-66268 - Groups filter in forum summary report
* MDL-66373 - Dates filter in forum summary report
* MDL-66297 - Link forum summary report to export of each user's post content
* MDL-66694 - Add columns for word count and character count to the forum summary report
* MDL-66768 - Add the ability to download the forum summary report

===Forum export===

* MDL-66075 - Forum export functionality
* MDL-66631 - Dates filter in forum export
* MDL-66808 - Forum export options for human-readable dates and removing HTML

===Forum grading===

* MDL-66074 - Create forum grading interface
* MDL-66358 - Display grading form in the grading panel
* MDL-66365 - Add a button to display the entire discussion for a post being graded
* MDL-67116 - Make 'require grade' an activity completion criterion for the forum
* MDL-66381 - Forum grading user search
* MDL-66360 - Forum grading option to send notification to student
* MDL-66906 - Forum view grades option for students
* MDL-66359 - Support restricting the user list to a specific group

===Forum UI improvements===

* MDL-66477 - Create settings side drawer for new discussion view
* MDL-64821 - Create new discussion view for forum
* MDL-66481 - Update display of discussion in discussion list table
* MDL-65129 - Search starred discussions only option in forum advanced search

===Question bank improvements===

* MDL-66553 - Display ID number and tags in the question bank UI
* MDL-66816 - Question bank: replace the row of edit icons with an Edit menu
* MDL-67153 - Allow question types to add extra actions to the Question bank edit menu

===H5P integration===

* MDL-66388 - Create a new button in Atto to add H5P content in anywhere from hp5.com and h5p.org external URLs
* MDL-66398 - Improve H5P filter to allow internal H5P content URLs
* MDL-66593 - Implement backup and restore process for H5P content
* MDL-67059 - Add Admin UI to manually upload H5P content-type libraries
* MDL-67043 - Web service to enable H5P offline access in the Moodle app
* MDL-67057 - Create a capability to update H5P content-type libraries
* MDL-67058 - Create a task to install H5P content-type libraries
* MDL-66609 - Create the basic skeleton, library and interfaces for rendering H5P content
* MDL-66399 - Improve H5P Atto button to upload content
* MDL-66397 - Create a new filter to convert h5p.com and h5p.org URLs to embed code

===Course relative dates (experimental)===

* MDL-66147 - Assignment due date relative to the student course start date
* MDL-66144 - Weeks format relative dates
* MDL-66143 - Course relative dates mode setting
* MDL-66148 - Option to override the assignment due date in a relative dates course

===Course overview===

* MDL-64901 - block_myoverview: Add admin setting to control the available layouts
* MDL-66016 - An admin can set which filters are available for users to select in their Dashboard course overview
* MDL-66017 - An admin can specify a course custom field as a filter for users to select in their Dashboard course overview
* MDL-63612 - Course card pattern colours may be specified by an admin
* MDL-65621 - Courses with course visibility set to hide should be labelled 'Hidden from students' in the course overview
* MDL-64860 - block_myoverview: Improve pagination widget
* MDL-64094 - Change 'Hidden' to 'Removed from view' in the course overview

===Emojis===

* MDL-65896 - Add emojis to messaging
* MDL-46779 - Atto should support full emoji

==Other highlights==

* MDL-65915 - Better progress display while re-grading quiz attempts
* MDL-66563 - Improve drag and drop question accessibility in high-contrast mode
''Items to be added soon...''

==For admins==

==For developers==

* MDL-66675 - New <tt>$CFG->behat_pause_on_fail</tt> option added.
* MDL-46267 - The <tt>$CFG->httpswwwroot</tt> was removed.
* MDL-66335 - New steps to navigate straight to any plugin web page. Plugins must implement their own resolver between page types and URLs.
* MDL-65349 - Profiling included and excluded URLs now are matched from start. Some adjustments may be needed.
* MDL-66633 - Quiz: quiz attempt API should let you create an attempt for a different user
* MDL-66709 - Components other than activity modules should be able to backup and restore question attempt data
* MDL-66754 - Question engine: report methods should not require a list of slots

==Security issues==

A number of security related issues were resolved. Details of these issues will be released after a period of approximately one week to allow system administrators to safely update to the latest version.

==See also==
*[[Moodle 3.7 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.8]]

[[fr:Notes de mise à jour de Moodle 3.8]]
[[es:Notas de Moodle 3.8]]

Availability API

2019-06-04T13:11:36Z

TimHunt:

{{Moodle 2.7}}

{{Infobox Project
|name = Availability API
|state = Integration review
|tracker = MDL-44070
|discussion = https://moodle.org/mod/forum/discuss.php?d=253958
|assignee = sam marshall (OU)
}}

= Availability API =

The availability API controls access to activities and sections. For example, a teacher could restrict access so that an activity cannot be accessed until a certain date, or so that a section cannot be accessed unless users have a certain grade in a quiz.

The conditional availability system defaults to off; users enable it from the advanced features page in settings. You can still call the API functions even if the system is turned off.

== Change from Moodle 2.6 and below ==

This replaces the previous API (2.6 and below) in conditionlib.php. The main differences in the new code are:

* Supports plugins for different types of condition.
* Allows conditions to be combined in Boolean logic tree structures.

If you have code using conditionlib.php, you'll see deprecation warnings advising you how to modify your code.

== Using the API ==

In most cases you do not need to use the API directly because the system handles it. For example, if you are writing a module:

* The system will automatically prevent users accessing your module if they do not meet an availability condition (unless they have the ability to access hidden activities). This happens when you call require_login and pass your module information.
* Your module's form will automatically have controls for setting availability restriction, as part of the standard form controls.

However for special cases you might need to use API features. There are two main uses, shown below.

=== Check if the current user can access an activity ===

To check if the current user can access an activity (supposing you have a $course and $cmid):

<code php>
$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cmid);
if ($cm->uservisible) {
// User can access the activity.
} else if ($cm->availableinfo) {
// User cannot access the activity, but on the course page they will
// see a link to it, greyed-out, with information (HTML format) from
// $cm->availableinfo about why they can't access it.
} else {
// User cannot access the activity and they will not see it at all.
}
</code>

There are similar properties for sections.

* You do not need to check the section properties when checking access for an activity, as the system takes these into account. (If the user cannot access a section, then $cm->uservisible will return false for all activities within the section.)
* You do not need to additionally check $cm->visible; $cm->uservisible already takes this into account too.

These properties are worked out for the current user. You can also obtain them for a different user by passing a user ID to get_fast_modinfo, although be aware that doing this repeatedly for different users will be slow.

=== Display a list of users who may be able to access the current activity ===

Sometimes you need to display a list of users who may be able to access the current activity.

While you could use the above approach for each user, this would be slow and also is generally not what you require. For example, if you have an activity such as an assignment which is set to be available to students until a certain date, and if you want to display a list of potential users within that activity, you probably don't want to make the list blank immediately the date occurs.

The system divides availability conditions into two types:

* Applied to user lists. (Group, grouping, profile condition.)
* Not applied to user lists. (Date, completion, grade.)

In general, the conditions which we expect are likely to change over time (such as dates) or as a result of user actions (such as grades) are not applied to user lists.

If you have a list of users (for example you could obtain this using one of the 'get enrolled users' functions), you can filter it to include only those users who are allowed to see an activity with this code:

<code php>
$info = new \core_availability\info_module($cm);
$filtered = $info->filter_user_list($users);
</code>

* This does not currently include the $cm->visible setting, nor does it take into account the viewhiddenactivities setting.

== Implementing new availability conditions ==

It is easy to write new availability conditions. See [[Availability conditions]].

== Using availability conditions in other areas ==

The availability API is provided for activities (course-modules) and sections. It is also possible to use it in other areas such as within a module. See [[Availability API for items within a module]].

== Programmatically setting availability conditions ==

If you want to programmatically set up an availability condition (e.g. set an activity to only be available to users of a particular group, the best code to do that is:

<code lang="php">
$restriction = \core_availability\tree::get_root_json(
[\availability_group\condition::get_json($group->id)]);
$DB->set_field('course_modules', 'availability',
json_encode($restriction), ['id' => $cmid]);
rebuild_course_cache($course->id, true);
</code>

Writing acceptance tests

2019-06-03T16:04:54Z

TimHunt:

== Introduction ==

This documentation gives some hints, how to write behat tests for core and for plugins. The focus of the documentation is on behat tests for plugins. They are written in some kind of natural language and describe how the front-end of moodle should behave, when a user interacts with it.

Each test consists of a set of so called steps in a GIVEN, WHEN, THEN style:
* '''GIVEN''': These steps outline the state of your moodle platform at the start of your test. Here you can create users, courses and plugin instances.
* '''WHEN''': These steps usually execute the functionality of your plugin, which is under test.
* '''THEN''': These steps describe the expected behaviour of your plugin. They usually check if different elements can or can't be seen.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

To initialize and run your tests, please follow the instructions of [[Running_acceptance_test]].

== Create your own tests ==
Behat tests are located within the directory tests/behat of your plugin.
The different tests are defined in files with the ending *.feature.
First, you have to define the header of your test:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
The tags on top of the feature description can be used to select specific test cases when running the tests.
The '@javascript' tag should only be used, if javascript is needed to execute your test. This is dependent on the step you will use in your definition.
Javascript tests are usually much slower than tests executed without javascript.

Afterwards you can specify a scenario:
<code behat>
@javascript
Scenario: Description of your scenario, which you want to test.
When I log in as "student1"
And I am on "Course 1" course homepage
</code>
Again you can define specific tags. Afterwards you write the steps, which should be executed during your test.

==== Multiple Scenarios ====
You can have an arbitrary amount of scenarios within a test. Please make sure they all belong to the same feature.
If you have certain steps, which should be executed for every scenario of a feature, you can define them using a background:
<code behat>
Background:
Given the following "courses" exist:
| fullname | shortname | category | groupmode |
| Course 1 | C1 | 0 | 1 |
And the following "users" exist:
| username | firstname | lastname | email |
| teacher1 | Theo | Teacher | teacher1@example.com |
</code>
This is usually used, to define the different '''GIVEN''' steps.

==== Use existing steps ====
There are different ways how to effectively browse the available existing steps:

====== Moodle Administration ======
Moodle offers within its administration menu under Site Administration > Development > Acceptance Testing a complete and searchable list of all available step definitions.
However, make sure you installed the behat test site first!

====== PhpStorm ======
In PhpStorm or IntelliJ you can install the behat extension. Then you get auto completions within feature files, which helps a lot during behat test development.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all the page's ids
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all the page's ids
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== Advanced use cases ====
Most of the time the usage of existing step definitions is straight forward. However, there are some exceptions were it might get complicated. Some of them are listed here:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
for field groups. Examples for such field groups are the duration field or the date_time_selector. These are not displayed as one single input field within the front-end but consist of multiple input fields within one row.
You can access each single input field of a group using
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Human-readable and relative dates ======
When testing plugins with deadlines, for instance for submissions, it is often necessary to set certain time values to dates relative to today.
You can specify a relative time enclosed within two ## blocks. For example:
* ## yesterday ##
* ## 2 days ago ##
You can use everything according to [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix your Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Acceptance testing

2019-04-25T20:32:24Z

TimHunt:

Moodle uses a framework called Behat to automatically test the user-interface. Tests can be written for each plugin, and for Moodle core.

* To run the existing tests, read [[Running acceptance test]]. You really need to do this first.
* To write new tests, read [[Writing acceptance tests]].
* To define new steps that can you used when writing tests, see [[Writing new acceptance test step definitions]]

Because Behat tests work through the Moodle user interface, the are a bit slow. Therefore, you should probably also use [[PHPUnit]] to test the detailed edge cases in your code.

[[Category:Behat]]

Writing new acceptance step step definitions

2019-04-25T20:27:45Z

TimHunt: TimHunt moved page Writing new acceptance step step definitions to Writing new acceptance test step definitions

#REDIRECT [[Writing new acceptance test step definitions]]

Writing new acceptance test step definitions

2019-04-25T20:27:45Z

TimHunt: TimHunt moved page Writing new acceptance step step definitions to Writing new acceptance test step definitions

As well as using the already existing steps described in [[Writing acceptance tests]], you can also define new steps.

This is most easily learned by looking at the examples that are already in the code. In any plugin, for example qtype_ddwtos, look at the file tests/behat/behat_qtype_ddwtos.php inside that plugin. Steps are defined by a function that has a special @Given, @When or @Then annotation in the PHPdoc comment. This gives a regular expression. Any step in a *.feature file which matches that regular expression will be translated into a call to that function.

In terms of making the Behat test work, it does not matter whether you use @Given, @When or @Then. However, to make your step understandable to people using your step, it is important to use the right word. Use @Given for steps that set things up, @When for steps that perform actions, and @Then for steps that verify what happened.

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

==See aslo==

* Behat project documentation for this: http://behat.org/en/latest/user_guide/context/definitions.html

[[Category:Behat]]

Writing new acceptance test step definitions

2019-04-25T20:27:34Z

TimHunt:

Writing new acceptance test step definitions

2019-04-25T20:19:43Z

TimHunt: TimHunt moved page Running acceptance test adding steps definitions to Writing new acceptance step step definitions without leaving a redirect

#REDIRECT [[Writing_acceptance_tests]]

Privacy API

2019-04-24T11:14:36Z

TimHunt: /* Retrieving the users in a context */

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

A polyfill has not been provided for this new interface, but we recognise that developers who are maintaining older versions (Moodle 3.3) will hit problems with this new interface not existing. We recommend doing something similar to the following example.
<code php>
<?php

namespace assignsubmission_example\privacy;

if (interface_exists('\core_privacy\local\request\userlist')) {
interface my_userlist extends \core_privacy\local\request\userlist{}
} else {
interface my_userlist {};
}

class provider implements my_userlist {

/**
* 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) {

}

/**
* 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) {

}

}
</code>

=====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 should only be data from that one context. Do not include subcontexts.
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 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) {

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

Running acceptance test

2019-04-17T09:46:33Z

TimHunt: /* 3. Set up Moodle */

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

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
<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/Compatibility changes

2019-04-15T15:40:43Z

TimHunt: /* See also */

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
<b>Summary</b>
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage<br>And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
|-
|After
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
|}
<b>Why did this change?</b>

UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===

<b>Summary</b>
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
|-
|After
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>
|}
<b>Why did this change?</b>

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

=== And I navigate to "Participants" node in "My courses > C1" ===
<b> Summary </b>
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1"<br>And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}
{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</code>
|-
|After
|<code>
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants
</code>
|}
<b> Why did this change? </b>

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]
[[Category:Behat]]

Running acceptance test

2019-04-15T14:28:29Z

TimHunt: /* Single run */

Writing acceptance tests

2019-04-15T14:23:34Z

TimHunt:

== Introduction ==

This documentation gives some hints, how to write behat tests for core and for plugins. The focus of the documentation is on behat tests for plugins. They are written in some kind of natural language and describe how the front-end of moodle should behave, when a user interacts with it.

Each test consists of a set of so called steps in a GIVEN, WHEN, THEN style:
* '''GIVEN''': These steps outline the state of your moodle platform at the start of your test. Here you can create users, courses and plugin instances.
* '''WHEN''': These steps usually execute the functionality of your plugin, which is under test.
* '''THEN''': These steps describe the expected behaviour of your plugin. They usually check if different elements can or can't be seen.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

To initialize and run your tests, please follow the instructions of [[Running_acceptance_test]].

== Create you own tests ==
Behat tests are located within the directory tests/behat of your plugin.
The different tests are defined in files with the ending *.feature.
First, you have to define the header of your test:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
The tags on top of the feature description can be used to select specific test cases when running the tests.
The '@javascript' tag should only be used, if javascript is needed to execute your test. This is dependent on the step you will use in your definition.
Javascript tests are usually much slower than tests executed without javascript.

Afterwards you can specify a scenario:
<code behat>
@javascript
Scenario: Description of your scenario, which you want to test.
When I log in as "student1"
And I am on "Course 1" course homepage
</code>
Again you can define specific tags. Afterwards you write the steps, which should be executed during your test.

==== Multiple Scenarios ====
You can have an arbitrary amount of scenarios within a test. Please make sure they all belong to the same feature.
If you have certain steps, which should be executed for every scenario of a feature, you can define them using a background:
<code behat>
Background:
Given the following "courses" exist:
| fullname | shortname | category | groupmode |
| Course 1 | C1 | 0 | 1 |
And the following "users" exist:
| username | firstname | lastname | email |
| teacher1 | Theo | Teacher | teacher1@example.com |
</code>
This is usually used, to define the different '''GIVEN''' steps.

==== Use existing steps ====
There are different ways how to effectively browse the available existing steps:

====== Moodle Administration ======
Moodle offers within its administration menu under Site Administration > Development > Acceptance Testing a complete and searchable list of all available step definitions.
However, make sure you installed the behat test site first!

====== PhpStorm ======
In PhpStorm or IntelliJ you can install the behat extension. Then you get auto completions within feature files, which helps a lot during behat test development.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all the page's ids
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all the page's ids
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== Advanced use cases ====
Most of the time the usage of existing step definitions is straight forward. However, there are some exceptions were it might get complicated. Some of them are listed here:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
for field groups. Examples for such field groups are the duration field or the date_time_selector. These are not displayed as one single input field within the front-end but consist of multiple input fields within one row.
You can access each single input field of a group using
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Relative dates ======
When testing plugins with deadlines, for instance for submissions, it is often necessary to set certain time values to dates relative to today.
You can specify a relative time enclosed within two ## blocks. For example:
* ## yesterday ##
* ## 2 days ago ##
You can use everything according to [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix you Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Writing acceptance tests

2019-04-15T14:08:09Z

TimHunt: /* Introduction */

== Introduction ==

This documentation gives some hints, how to write behat tests for core and for plugins. The focus of the documentation is on behat tests for plugins. They are written in some kind of natural language and describe how the front-end of moodle should behave, when a user interacts with it.

Each test consists of a set of so called steps in a GIVEN, WHEN, THEN style:
* '''GIVEN''': These steps outline the state of your moodle platform at the start of your test. Here you can create users, courses and plugin instances.
* '''WHEN''': These steps usually execute the functionality of your plugin, which is under test.
* '''THEN''': These steps describe the expected behaviour of your plugin. They usually check if different elements can or can't be seen.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

To initialize and run your tests, please follow the instructions of [[Running_acceptance_test]].

== Create you own tests ==
Behat tests are located within the directory tests/behat of your plugin.
The different tests are defined in files with the ending *.feature.
First, you have to define the header of your test:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
The tags on top of the feature description can be used to select specific test cases when running the tests.
The '@javascript' tag should only be used, if javascript is needed to execute your test. This is dependent on the step you will use in your definition.
Javascript tests are usually much slower than tests executed without javascript.

Afterwards you can specify a scenario:
<code behat>
@javascript
Scenario: Description of your scenario, which you want to test.
When I log in as "student1"
And I am on "Course 1" course homepage
</code>
Again you can define specific tags. Afterwards you write the steps, which should be executed during your test.

==== Multiple Scenarios ====
You can have an arbitrary amount of scenarios within a test. Please make sure they all belong to the same feature.
If you have certain steps, which should be executed for every scenario of a feature, you can define them using a background:
<code behat>
Background:
Given the following "courses" exist:
| fullname | shortname | category | groupmode |
| Course 1 | C1 | 0 | 1 |
And the following "users" exist:
| username | firstname | lastname | email |
| teacher1 | Theo | Teacher | teacher1@example.com |
</code>
This is usually used, to define the different '''GIVEN''' steps.

==== Use existing steps ====
There are different ways how to effectively browse the available existing steps:

====== Moodle Administration ======
Moodle offers within its administration menu under Site Administration > Development > Acceptance Testing a complete and searchable list of all available step definitions.
However, make sure you installed the behat test site first!

====== PhpStorm ======
In PhpStorm or IntelliJ you can install the behat extension. Then you get auto completions within feature files, which helps a lot during behat test development.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all the page's ids
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all the page's ids
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== Advanced use cases ====
Most of the time the usage of existing step definitions is straight forward. However, there are some exceptions were it might get complicated. Some of them are listed here:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
for field groups. Examples for such field groups are the duration field or the date_time_selector. These are not displayed as one single input field within the front-end but consist of multiple input fields within one row.
You can access each single input field of a group using
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Relative dates ======
When testing plugins with deadlines, for instance for submissions, it is often necessary to set certain time values to dates relative to today.
You can specify a relative time enclosed within two ## blocks. For example:
* ## yesterday ##
* ## 2 days ago ##
You can use everything according to [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

[[Category:Behat]]

Using the question engine from module

2019-04-15T10:57:41Z

TimHunt:

{{Template:Question_engine_2}}
This page explains how to use the new Moodle [[Question Engine 2|question engine]] in an activity module you are developing.

Previous section: [[Developing_a_Question_Type|Developing a Question Type]]

The first example of a module that uses the question engine is the quiz module. Looking at how the quiz code works will let you see a real working example of what is explained on this page. Another, much simpler example to look at is <tt>question/preview.php</tt>, and https://github.com/moodleou/moodle-filter_embedquestion/blob/master/showquestion.php is simpler still.

Note that all the question engine code has extensive PHP documentor comments that should explain the purpose of every class and method. This document is supposed to provide an overview of the key points to get you started. It does not attempt to duplicate all the details in the PHPdocs.

==Overview==

The key class you will be working with is <tt>question_usage_by_activity</tt>. This tracks an attempt at some questions, for example a quiz attempt. The usage should provide all the interface methods you need to do things with the question engine. You should rarely need to dive deeper into the inner workings of the question engine than this.

A usage is a collection of <tt>question_attempt</tt> objects. A question attempt represents the state of the user's attempt at one question within the usage. When you add a question to the usage, you get back a '''slot''' number. This serves to index that question within the attempt. Using slot numbers like this means that the same question can be added more than once to the same usage. A lot of the usage API calls take this slot number to indicate which question attempt to operate on. Other API methods let you perform batch actions on all the question attempts within the usage.

==Starting an attempt at some questions==

The example code in this section all came from <tt>mod/quiz/startattempt.php</tt>.

===Creating the usage===

To create a new usage, ask the question engine:
<code php>
$quba = question_engine::make_questions_usage_by_activity('mod_quiz', $quizobj->get_context());
$quba->set_preferred_behaviour($quiz->preferredbehaviour);
</code>

You will see that the constructor takes the plugin name (using the Moodle 2.0 'frankenstyle' naming convention) and the context that owns the usage. Usages should be cleaned up automatically when a context is deleted or a plugin un-installed. You also have to tell the usage which behaviour should be used when creating the attempt at each question.

===Adding questions===

Having got a usage, you will probably then want to add some questions to it. The question data you loaded from the database (probably using the <tt>get_question_options</tt> function) come in a form suitable for data handling like import/export, backup/restore, and so on. We need to convert that to an <tt>question_definition</tt> object. That can be done using the <tt>question_bank::make_question</tt> method. Alternatively, you could just use the <tt>question_bank::load_question</tt> method, but that can only load one question at a time.

Once you have a <tt>question_definition</tt> object, you add it to the usage by calling the <tt>add_question</tt> method passing the question definition, and also the score you want this question marked out of. You get back the slot number that has been assigned to this question. The slot numbers are allocated in order, starting from 1. You can rely on that numbering convention. For example, the quiz module uses the slot numbers to make sure the grade for each question lines up properly in the reports.

Here is the applicable code from the quiz module
<code php>
foreach ($quizobj->get_questions() as $i => $questiondata) {
$question = question_bank::make_question($questiondata);
$idstoslots[$i] = $quba->add_question($question, $questiondata->maxmark);
}
</code>

===Starting the question attempts===

The usage does not do much when the question is added. Before the user can start interacting with the question, you have to start it. You can either do that in bulk:
<code php>
$quba->start_all_questions();
</code>
or you can start just one particular question using the <tt>start_question($slot)</tt> method.

===Saving the usage===

So far, all these method calls have just built up a data structure in memory. If you want to keep it, you have to save it in the database. Fortunately, that is easy:
<code php>
question_engine::save_questions_usage_by_activity($quba);
</code>

The usage is stored as a row in the <tt>question_usages</tt> table (plus rows in other tables). To get the id of the usage, call <tt>$quba->get_id()</tt> after you have saved it.

==Displaying questions==

Suppose that you wish to display a page that contains several questions from the usage. The questions to display will be the ones whose slot numbers are in an array called <tt>$slotsonpage</tt>.

The example code in this section is derived from code used by <tt>mod/quiz/attempt.php</tt>. However, the quiz code is split between <tt>mod/quiz/attempt.php</tt> and the <tt>quiz_attempt</tt> class in <tt>mod/quiz/attemptlib.php</tt>. That separation means that if I used the real quiz code in this tutorial, it would be unnecessarily hard to understand. Instead, I have simplified the examples below. If you are interested, you should be able to match up what you see below with the real quiz code.

===Loading the usage===

At the end of the last section, you had just saved the usage to the database. To display the questions as part of a different script, they must be loaded from the database again. Once again you ask the question engine to do this:
<code php>
$quba = question_engine::load_questions_usage_by_activity($usageid);
</code>

The id that you pass to this method is the id you got from <tt>$quba->get_id()</tt> after saving the usage.

===The question form===

Within the page, all the questions have to be wrapped in a HTML <tt><nowiki><form></nowiki></tt> tag. This form needs to POST to a scripts that processes the submitted data ([[#Processing_responses|see below]]).
<code php>
echo '<form id="responseform" method="post" action="' . $processurl .
'" enctype="multipart/form-data" accept-charset="utf-8">', "\n<div>\n";

$PAGE->requires->js_init_call('M.core_question_engine.init_form',
array('#responseform'), false, 'core_question_engine');

echo '<input type="hidden" name="slots" value="' . implode(',', $slotsonpage) . "\" />\n";
echo '<input type="hidden" name="scrollpos" value="" />';
</code>

The <tt>enctype</tt> and <tt>accept-charset</tt> parameters are important. Please copy them. The form must have an id, and you must then write some JavaScript that passes that id to to the <tt>question_init_form</tt> function. That function is defined in <tt>question/qengine.js</tt> if you want to find out what it does and why it is important.

You should output a hidden form field <tt>slots</tt> that contains a comma-separated list of the slot numbers that appear on this page. That is not absolutely necessary, but it will make processing the form submission much more efficient.

Another nicety is the <tt>scrollpos</tt> hidden field. Some question behaviours, for example the interactive behaviour, have submit buttons that do something to the question. When the user clicks this button, it is nice if when the page re-displays, it is scrolled to exactly the same place where it was. The question engine has JavaScript which, if it finds a <tt>scrollpos</tt> hidden field, will automatically save the scroll position to it when a button is clicked, and cause the page to scroll to that position when it reloads.

===Outputting the questions===

Finally, you can actually print the questions. Well, there is one more thing to take care of first. To control how the question appears, you must prepare a <tt>question_display_options</tt> object that describes what should be visible. For example:
<code php>
$options = new question_display_options();
$options->marks = question_display_options::MAX_ONLY;
$options->markdp = 2; // Display marks to 2 decimal places.
$options->feedback = question_display_options::VISIBLE;
$options->generalfeedback = question_display_options::HIDDEN;
// etc.
</code>

(In the quiz code, the display options actually come from the quiz settings.) Then you really are ready to output the questions
<code php>
foreach ($slotsonpage as $displaynumber => $slot) {
echo $quba->render_question($slot, $options, $displaynumber);
}
</code>

Here <tt>$displaynumber</tt> is the 'question number' you want printed next to each question. This is not necessarily the same as the slot number. For example, in the quiz, Description 'questions' are not numbered, although they take up a slot. It does not have to be a single integer (once MDL-62358 is fixed) if you have some other scheme for identifiying quesitions in your activity. For example you could pass '4.3.1' or '7 of 10' if that is what your activity needs. If you don't pass in a number to display, that is, if you pass null, then the question is printed without a Question X heading.

==Processing responses==

Once again, the example here are inspired by real code from the quiz module, in this case <tt>mod/quiz/processattempt.php</tt>, but simplified to remove mention of the <tt>quiz_attempt</tt> class.

===The simple case===

Normally, you just need to do something like:
<code php>
$timenow = time();
$transaction = $DB->start_delegated_transaction();

$quba = question_engine::load_questions_usage_by_activity($usageid);
$quba->process_all_actions($timenow);
question_engine::save_questions_usage_by_activity($quba);

$transaction->allow_commit();
</code>

Behind the scenes there is, of course, a lot going on, including the use of the <tt>slots</tt> parameter to control which questions are processed.

There may also be additional work you need to do. For example, in the quiz (before the <tt>commit_sql()</tt> line) there is:

<code php>
if ($attempt->timefinish) {
$attempt->sumgrades = $quba->get_total_mark();
}
$attempt->timemodified = $timenow;
$DB->update_record('quiz_attempts', $attempt);
</code>

===More selective processing===

If you want something other than the default processing, you can use code like <tt>$submitteddata = $quba->extract_responses($slot); $quba->process_action($slot, $submitteddata);</tt> or something similar.

===Handling scrollpos===

You will remember that when we printed the questions, we created a <tt>scrollpos</tt> hidden field. Presumably, after you have processed the submission, you will redirect the user back to a page to display the questions again. In that case, you need to get the <tt>scrollpos</tt> parameter, and add it on to the URL you redirect to:

<code php>
// With the other required/optional_param calls at the start of processattempt.php.
$scrollpos = optional_param('scrollpos', '', PARAM_RAW);

// ... a bit later in the file
$nexturl = new moodle_url(/* something */);
if ($scrollpos !== '') {
$nexturl->param('scrollpos', (int) $scrollpos);
}

// ... after all the processing is done.
redirect($nexturl);
</code>

==Reports==

Places like the quiz reports, we need to get data about a lot of usages at the same time. There are methods on the <tt>question_engine_data_mapper</tt> to do this. You should never access the data in the question engine tables directly.

For example from the quiz grades report. (Again the example code has been simplified.)
<code php>
// $qubaids is an array of integer ids.
$qubaidscondition = new qubaid_list($qubaids);

$dm = new question_engine_data_mapper();
$latesstepdata = $dm->load_questions_usages_latest_steps(
$qubaidscondition, $slots);
</code>

<tt>qubaid_list</tt> is a subclass of the <tt>qubaid_condition</tt> class. This is an efficient way to represent a set of usage ids in a way that can be used in database queries. The other main subclass is <tt>qubaid_join</tt>. That could be used like this:
<code php>
$qubaidscondition = new qubaid_join('{quiz_attempts} quiza', 'quiza.uniqueid',
'quiza.quiz = :quizaquiz', array('quizaquiz' => $quizid))
</code>

Another example, from the quiz manual grading report is
<code php>
$dm = new question_engine_data_mapper();
$statesummary = $dm->load_questions_usages_question_state_summary(
$qubaidscondition, $slots);
</code>

(Perhaps the use of the class <tt>question_engine_data_mapper</tt> should be hidden inside a helper class <tt>question_engine_reporter</tt>?)

==Other methods==

===Methods to help with settings UI===

When you want to present users with a choice of question behaviour (for example, the quiz How questions behave option) use
<code php>
$options = question_engine::get_behaviour_options();
</code>

Question marks are stored in the database to a fixed number of decimal places. To get a list of possible decimal place display options, use
<code php>
$options = question_engine::get_dp_options();
</code>

===Clean-up methods===

To delete usages you no longer need:
<code php>
// A single usage ...
question_engine::delete_questions_usage_by_activity($qubaid);

// ... or many.
question_engine::delete_questions_usage_by_activities(
new qubaid_join('{quiz_attempts} quiza', 'quiza.uniqueid',
'quiza.quiz = :quizaquiz', array('quizaquiz' => $quizid)));
</code>

===Changing the score of a question in all attempts===

Suppose you change the number of marks awarded to question 2 in the quiz, you need to change that information in every attempt at that quiz, you can do that with a call like
<code php>
question_engine::set_max_mark_in_attempts($qubaids, $slot, $newmaxmark);
</code>

===Re-grading a question===

You only need to re-grade a question when the question definition is edited, for example to change the scoring rules. If you are just changing the maximum possible score for a question, see the previous sub-section.

This code example is adapted from <tt>mod/quiz/report/overview/report.php</tt>. It re-grades selected slots within a quiz attempt.
<code php>
$transaction = $DB->start_delegated_transaction();
$quba = question_engine::load_questions_usage_by_activity($attempt->uniqueid);

foreach ($slots as $slot) {
$oldfraction[$slot] = $quba->get_question_fraction($slot);
$quba->regrade_question($slot);
$newfraction[$slot] = $quba->get_question_fraction($slot);
}

question_engine::save_questions_usage_by_activity($quba);
$attempt->sumgrades = $quba->get_total_mark();
update_record('quiz_attempts', $attempt);
$transaction->allow_commit();
</code>

==See also==

In the next section, [[Question Engine 2:Implementation plan|Implementation plan]] outlines how I will implement this proposal.

* https://github.com/moodleou/moodle-filter_embedquestion/blob/master/showquestion.php is probably the simplest example code that displays a question and lets a user interact with it.

* The PHP documenter comments that explain the purposes of every method in the question engine code.
* Back to [[Question_Engine_2|Question Engine 2]]

Using the question engine from module

2019-04-15T10:56:42Z

TimHunt: /* See also */

{{Template:Question_engine_2}}
This page explains how to use the new Moodle [[Question Engine 2|question engine]] in an activity module you are developing.

Previous section: [[Developing_a_Question_Type|Developing a Question Type]]

The first example of a module that uses the question engine is the quiz module. Looking at how the quiz code works will let you see a real working example of what is explained on this page. Another, much simpler example to look at is <tt>question/preview.php</tt>.

Note that all the question engine code has extensive PHP documentor comments that should explain the purpose of every class and method. This document is supposed to provide an overview of the key points to get you started. It does not attempt to duplicate all the details in the PHPdocs.

==Overview==

The key class you will be working with is <tt>question_usage_by_activity</tt>. This tracks an attempt at some questions, for example a quiz attempt. The usage should provide all the interface methods you need to do things with the question engine. You should rarely need to dive deeper into the inner workings of the question engine than this.

A usage is a collection of <tt>question_attempt</tt> objects. A question attempt represents the state of the user's attempt at one question within the usage. When you add a question to the usage, you get back a '''slot''' number. This serves to index that question within the attempt. Using slot numbers like this means that the same question can be added more than once to the same usage. A lot of the usage API calls take this slot number to indicate which question attempt to operate on. Other API methods let you perform batch actions on all the question attempts within the usage.

==Starting an attempt at some questions==

The example code in this section all came from <tt>mod/quiz/startattempt.php</tt>.

===Creating the usage===

To create a new usage, ask the question engine:
<code php>
$quba = question_engine::make_questions_usage_by_activity('mod_quiz', $quizobj->get_context());
$quba->set_preferred_behaviour($quiz->preferredbehaviour);
</code>

You will see that the constructor takes the plugin name (using the Moodle 2.0 'frankenstyle' naming convention) and the context that owns the usage. Usages should be cleaned up automatically when a context is deleted or a plugin un-installed. You also have to tell the usage which behaviour should be used when creating the attempt at each question.

===Adding questions===

Having got a usage, you will probably then want to add some questions to it. The question data you loaded from the database (probably using the <tt>get_question_options</tt> function) come in a form suitable for data handling like import/export, backup/restore, and so on. We need to convert that to an <tt>question_definition</tt> object. That can be done using the <tt>question_bank::make_question</tt> method. Alternatively, you could just use the <tt>question_bank::load_question</tt> method, but that can only load one question at a time.

Once you have a <tt>question_definition</tt> object, you add it to the usage by calling the <tt>add_question</tt> method passing the question definition, and also the score you want this question marked out of. You get back the slot number that has been assigned to this question. The slot numbers are allocated in order, starting from 1. You can rely on that numbering convention. For example, the quiz module uses the slot numbers to make sure the grade for each question lines up properly in the reports.

Here is the applicable code from the quiz module
<code php>
foreach ($quizobj->get_questions() as $i => $questiondata) {
$question = question_bank::make_question($questiondata);
$idstoslots[$i] = $quba->add_question($question, $questiondata->maxmark);
}
</code>

===Starting the question attempts===

The usage does not do much when the question is added. Before the user can start interacting with the question, you have to start it. You can either do that in bulk:
<code php>
$quba->start_all_questions();
</code>
or you can start just one particular question using the <tt>start_question($slot)</tt> method.

===Saving the usage===

So far, all these method calls have just built up a data structure in memory. If you want to keep it, you have to save it in the database. Fortunately, that is easy:
<code php>
question_engine::save_questions_usage_by_activity($quba);
</code>

The usage is stored as a row in the <tt>question_usages</tt> table (plus rows in other tables). To get the id of the usage, call <tt>$quba->get_id()</tt> after you have saved it.

==Displaying questions==

Suppose that you wish to display a page that contains several questions from the usage. The questions to display will be the ones whose slot numbers are in an array called <tt>$slotsonpage</tt>.

The example code in this section is derived from code used by <tt>mod/quiz/attempt.php</tt>. However, the quiz code is split between <tt>mod/quiz/attempt.php</tt> and the <tt>quiz_attempt</tt> class in <tt>mod/quiz/attemptlib.php</tt>. That separation means that if I used the real quiz code in this tutorial, it would be unnecessarily hard to understand. Instead, I have simplified the examples below. If you are interested, you should be able to match up what you see below with the real quiz code.

===Loading the usage===

At the end of the last section, you had just saved the usage to the database. To display the questions as part of a different script, they must be loaded from the database again. Once again you ask the question engine to do this:
<code php>
$quba = question_engine::load_questions_usage_by_activity($usageid);
</code>

The id that you pass to this method is the id you got from <tt>$quba->get_id()</tt> after saving the usage.

===The question form===

Within the page, all the questions have to be wrapped in a HTML <tt><nowiki><form></nowiki></tt> tag. This form needs to POST to a scripts that processes the submitted data ([[#Processing_responses|see below]]).
<code php>
echo '<form id="responseform" method="post" action="' . $processurl .
'" enctype="multipart/form-data" accept-charset="utf-8">', "\n<div>\n";

$PAGE->requires->js_init_call('M.core_question_engine.init_form',
array('#responseform'), false, 'core_question_engine');

echo '<input type="hidden" name="slots" value="' . implode(',', $slotsonpage) . "\" />\n";
echo '<input type="hidden" name="scrollpos" value="" />';
</code>

The <tt>enctype</tt> and <tt>accept-charset</tt> parameters are important. Please copy them. The form must have an id, and you must then write some JavaScript that passes that id to to the <tt>question_init_form</tt> function. That function is defined in <tt>question/qengine.js</tt> if you want to find out what it does and why it is important.

You should output a hidden form field <tt>slots</tt> that contains a comma-separated list of the slot numbers that appear on this page. That is not absolutely necessary, but it will make processing the form submission much more efficient.

Another nicety is the <tt>scrollpos</tt> hidden field. Some question behaviours, for example the interactive behaviour, have submit buttons that do something to the question. When the user clicks this button, it is nice if when the page re-displays, it is scrolled to exactly the same place where it was. The question engine has JavaScript which, if it finds a <tt>scrollpos</tt> hidden field, will automatically save the scroll position to it when a button is clicked, and cause the page to scroll to that position when it reloads.

===Outputting the questions===

Finally, you can actually print the questions. Well, there is one more thing to take care of first. To control how the question appears, you must prepare a <tt>question_display_options</tt> object that describes what should be visible. For example:
<code php>
$options = new question_display_options();
$options->marks = question_display_options::MAX_ONLY;
$options->markdp = 2; // Display marks to 2 decimal places.
$options->feedback = question_display_options::VISIBLE;
$options->generalfeedback = question_display_options::HIDDEN;
// etc.
</code>

(In the quiz code, the display options actually come from the quiz settings.) Then you really are ready to output the questions
<code php>
foreach ($slotsonpage as $displaynumber => $slot) {
echo $quba->render_question($slot, $options, $displaynumber);
}
</code>

Here <tt>$displaynumber</tt> is the 'question number' you want printed next to each question. This is not necessarily the same as the slot number. For example, in the quiz, Description 'questions' are not numbered, although they take up a slot. It does not have to be a single integer (once MDL-62358 is fixed) if you have some other scheme for identifiying quesitions in your activity. For example you could pass '4.3.1' or '7 of 10' if that is what your activity needs. If you don't pass in a number to display, that is, if you pass null, then the question is printed without a Question X heading.

==Processing responses==

Once again, the example here are inspired by real code from the quiz module, in this case <tt>mod/quiz/processattempt.php</tt>, but simplified to remove mention of the <tt>quiz_attempt</tt> class.

===The simple case===

Normally, you just need to do something like:
<code php>
$timenow = time();
$transaction = $DB->start_delegated_transaction();

$quba = question_engine::load_questions_usage_by_activity($usageid);
$quba->process_all_actions($timenow);
question_engine::save_questions_usage_by_activity($quba);

$transaction->allow_commit();
</code>

Behind the scenes there is, of course, a lot going on, including the use of the <tt>slots</tt> parameter to control which questions are processed.

There may also be additional work you need to do. For example, in the quiz (before the <tt>commit_sql()</tt> line) there is:

<code php>
if ($attempt->timefinish) {
$attempt->sumgrades = $quba->get_total_mark();
}
$attempt->timemodified = $timenow;
$DB->update_record('quiz_attempts', $attempt);
</code>

===More selective processing===

If you want something other than the default processing, you can use code like <tt>$submitteddata = $quba->extract_responses($slot); $quba->process_action($slot, $submitteddata);</tt> or something similar.

===Handling scrollpos===

You will remember that when we printed the questions, we created a <tt>scrollpos</tt> hidden field. Presumably, after you have processed the submission, you will redirect the user back to a page to display the questions again. In that case, you need to get the <tt>scrollpos</tt> parameter, and add it on to the URL you redirect to:

<code php>
// With the other required/optional_param calls at the start of processattempt.php.
$scrollpos = optional_param('scrollpos', '', PARAM_RAW);

// ... a bit later in the file
$nexturl = new moodle_url(/* something */);
if ($scrollpos !== '') {
$nexturl->param('scrollpos', (int) $scrollpos);
}

// ... after all the processing is done.
redirect($nexturl);
</code>

==Reports==

Places like the quiz reports, we need to get data about a lot of usages at the same time. There are methods on the <tt>question_engine_data_mapper</tt> to do this. You should never access the data in the question engine tables directly.

For example from the quiz grades report. (Again the example code has been simplified.)
<code php>
// $qubaids is an array of integer ids.
$qubaidscondition = new qubaid_list($qubaids);

$dm = new question_engine_data_mapper();
$latesstepdata = $dm->load_questions_usages_latest_steps(
$qubaidscondition, $slots);
</code>

<tt>qubaid_list</tt> is a subclass of the <tt>qubaid_condition</tt> class. This is an efficient way to represent a set of usage ids in a way that can be used in database queries. The other main subclass is <tt>qubaid_join</tt>. That could be used like this:
<code php>
$qubaidscondition = new qubaid_join('{quiz_attempts} quiza', 'quiza.uniqueid',
'quiza.quiz = :quizaquiz', array('quizaquiz' => $quizid))
</code>

Another example, from the quiz manual grading report is
<code php>
$dm = new question_engine_data_mapper();
$statesummary = $dm->load_questions_usages_question_state_summary(
$qubaidscondition, $slots);
</code>

(Perhaps the use of the class <tt>question_engine_data_mapper</tt> should be hidden inside a helper class <tt>question_engine_reporter</tt>?)

==Other methods==

===Methods to help with settings UI===

When you want to present users with a choice of question behaviour (for example, the quiz How questions behave option) use
<code php>
$options = question_engine::get_behaviour_options();
</code>

Question marks are stored in the database to a fixed number of decimal places. To get a list of possible decimal place display options, use
<code php>
$options = question_engine::get_dp_options();
</code>

===Clean-up methods===

To delete usages you no longer need:
<code php>
// A single usage ...
question_engine::delete_questions_usage_by_activity($qubaid);

// ... or many.
question_engine::delete_questions_usage_by_activities(
new qubaid_join('{quiz_attempts} quiza', 'quiza.uniqueid',
'quiza.quiz = :quizaquiz', array('quizaquiz' => $quizid)));
</code>

===Changing the score of a question in all attempts===

Suppose you change the number of marks awarded to question 2 in the quiz, you need to change that information in every attempt at that quiz, you can do that with a call like
<code php>
question_engine::set_max_mark_in_attempts($qubaids, $slot, $newmaxmark);
</code>

===Re-grading a question===

You only need to re-grade a question when the question definition is edited, for example to change the scoring rules. If you are just changing the maximum possible score for a question, see the previous sub-section.

This code example is adapted from <tt>mod/quiz/report/overview/report.php</tt>. It re-grades selected slots within a quiz attempt.
<code php>
$transaction = $DB->start_delegated_transaction();
$quba = question_engine::load_questions_usage_by_activity($attempt->uniqueid);

foreach ($slots as $slot) {
$oldfraction[$slot] = $quba->get_question_fraction($slot);
$quba->regrade_question($slot);
$newfraction[$slot] = $quba->get_question_fraction($slot);
}

question_engine::save_questions_usage_by_activity($quba);
$attempt->sumgrades = $quba->get_total_mark();
update_record('quiz_attempts', $attempt);
$transaction->allow_commit();
</code>

==See also==

In the next section, [[Question Engine 2:Implementation plan|Implementation plan]] outlines how I will implement this proposal.

* https://github.com/moodleou/moodle-filter_embedquestion/blob/master/showquestion.php is probably the simplest example code that displays a question and lets a user interact with it.

* The PHP documenter comments that explain the purposes of every method in the question engine code.
* Back to [[Question_Engine_2|Question Engine 2]]

Moodle App Plugins Development Guide

2019-04-03T14:02:16Z

TimHunt: /* core-link */

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

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

Moodle App Plugins Development Guide

2019-04-03T13:34:40Z

TimHunt: /* Step by step example */

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

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

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

Question types

2019-04-01T13:29:03Z

TimHunt: /* Unit tests */

{{Template:Question_engine_2}}
=Question type plug in development=
This page explains how to write a question type that works with the new Moodle [[Question Engine 2|question engine]], the question engine introduced with Moodle 2.1 .

For instructions on making a question type for versions of Moodle prior to Moodle 2.1, see [[Question_type_plugin_how_to]].

Previous section: [[Developing a Question Behaviour|Developing a Question Behaviour]]

==Existing question type plug ins are helpful guides==

To learn to write question types, you are highly encouraged to read the code of some of the existing question types included in the Moodle code base, also there are many more examples of question types in the [https://github.com/moodleou/ Open University github repository] and even more examples of question types can be found in [https://moodle.org/plugins/browse.php?list=category&id=29 the question type category of the Moodle plugins database].

===Existing question types and some of their features===

Below is a list of question types with their features, it is a good idea to examine the code of these question types especially ones that have features you may need for your new question type.

If your question type will be GPLed then of course you can reuse the code in these question types either by cut and paste or by inheriting code from these question types.

* Questions included in Moodle
** true false, short answer
*** simplest question types
** Essay question type (essay)
*** manually not automatically graded.
** Calculated question
*** Uses a multipage question editing form
** Multiple choice (multichoice)
*** there is actually no reason why you should only have a single <tt>question_definition</tt> class for your question type. You may decide, depending on the question options, to use different definition classes where question options cause questions to behave in different ways. The multiple-choice question type does this, using different definition and renderer classes for single-response and multiple-response questions (but with common subclasses). This is possible because your question type can override the <tt>question_type::make_question_instance</tt> and <tt>question_definition::get_renderer</tt> methods.
* Contrib questions
** [https://moodle.org/plugins/view.php?plugin=qtype_ddwtos Drag and drop into text (ddwtos)]
*** Use of YUI js module to add more interactivity.
** [https://moodle.org/plugins/view.php?plugin=qtype_ddmarker Drag and drop markers question type (ddmarker)]
*** Use of YUI js module to add more interactivity.
** [https://moodle.org/plugins/view.php?plugin=qtype_ddimageortext Drag and drop (image or text) onto image (ddimageortext)]
*** inherits code from Select missing words (gapselect).
*** also contains base classes which inherit from Select missing words (gapselect) and are used by Drag and drop markers
*** Use of YUI js module to add more interactivity.
** [https://moodle.org/plugins/view.php?plugin=qtype_oumultiresponse OU multiple response (oumultiresponse)]
*** Question with multiple parts where grade is calculated by part for multiple attempts, student is given the grade for each part for the first time they got that part right or partially right.
** [https://moodle.org/plugins/view.php?plugin=qtype_pmatch Pmatch question type (pmatch)]
** [https://moodle.org/plugins/view.php?plugin=qtype_pmatchjme Pattern match with JME editor (pmatchjme)]
*** Embeds a JAVA applet in the question which collects the student response and sends that to the server.
** [https://moodle.org/plugins/view.php?plugin=qbehaviour_opaque Question managed by a remote engine (opaque)]
*** communicates with an external system by a web service protocol based on SOAP to "delegate the rendering of questions, the scoring of responses and the generation of feedback to a remote question engine." See https://docs.moodle.org/dev/Opaque
** [https://moodle.org/plugins/view.php?plugin=qtype_gapselect Select missing words (gapselect)]
** [https://moodle.org/plugins/view.php?plugin=qtype_varnumeric Variable numeric question type (varnumeric)]
*** Code inherited from Variable numeric set.
** [https://moodle.org/plugins/view.php?plugin=qtype_varnumericset Variable numeric set question type (varnumericset)]

==Question type plug in template==

There is a [https://github.com/jamiepratt/moodle-qtype_TEMPLATE/ question type plug in template available on github]. See the [https://github.com/jamiepratt/moodle-qtype_TEMPLATE/blob/master/README.md README.md] file on the front page of the repository for more info about this template and how you are recommended to use it.

==The question engine itself is well commented==

Also note that all the question engine code has extensive PHP documenter comments that should explain the purpose of every class and method. This document is supposed to provide an overview of the key points to get you started. It does not attempt to duplicate all the details in the PHPdocs.

This document assumes that you understand the data model, where a question attempt comprises a number of steps, and each step has some properties like a state and a mark, and an array of submitted data. [[Question_Engine_2:Overview|See the question engine overview doc for background]].

===Changes in the question type plug in api between Moodle versions===

[https://github.com/moodle/moodle/blob/master/question/type/upgrade.txt question/type/upgrade.txt] details the changes in the question type plug in api between Moodle versions.

==File layout==

Question types live in a folder in <tt>question/type</tt>. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the <tt>question/type/mytype/</tt> folder we would have:

; edit_YOURQTYPENAME_form.php : is the moodle_form used to define your question editing form. See [lib/formslib.php_Form_Definition] for details of how to use the formslib api.
; questiontype.php : Defines the <tt>qtype_mytype</tt> class. This must extend <tt>question_type</tt>.
; question.php : This contains the definition of the <tt>qtype_mytype_question</tt> class, which should extend the <tt>question_definition</tt> base class.
; renderer.php : This contains the definition of the <tt>qtype_mytype_renderer</tt> class, which should extend the <tt>qtype_renderer</tt> base class.
; tests/... : Contains the [[PHPUnit|unit tests]] and [[Acceptance_testing|Behat tests]] for this question type. You are strongly encouraged to write thorough unit tests to ensure the correctness of your question type.
; lang/en/qtype_myqtype.php : English language strings for this question type. You can, of course, include other languages too. The language file must define at least the strings giving the model a name etc., for example :

$string['pluginname'] = 'YOURQTYPENAME';
$string['pluginname_help'] = 'Create a .. description of your question type';
$string['pluginname_link'] = 'question/type/YOURQTYPENAME';
$string['pluginnameadding'] = 'Adding a YOURQTYPENAME question';
$string['pluginnameediting'] = 'Editing a YOURQTYPENAME question';
$string['pluginnamesummary'] = 'A YOURQTYPENAME question type which allows...';

; lib.php : There is an importnat callback here that is called by the question engine to allow access to files used by questions. As with other plugins, you can put library code here, but in modern Moodle code it is better to use the classes/ folder.
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|as normal]]. See [[#Database_tables]] below.
; db/access.php : Defines any capabilities required by this question type. This is very rarely needed.
; version.php : [[version.php|version information]] for the question type. Also you can included in here which version no of core Moodle and/or other question types this module requires. Bumping up the question version will trigger the appropriate code in upgrade.php to be run when someone accesses {yourwwwroot}/admin/.
; styles.css : contains the styles used by your question type. You should preface all your selectors with .que.YOURQTYPENAME so that the styles are only applied to your question type which is wrapped in a div with class 'que' and 'YOURQTYPENAME'.
; pix/icon.svg: is the 16 * 16 px icon that appears next to your question type in the question type selection panel. (Can aslo be .png or .gif.)
; backup/moodle2/ : contains the files to implement backup and restore for your question type.
; classes/ : As with any Moodle plugin, you can put any extra classes you want to use to organise your code in here, and they will be [[Automatic_class_loading|auto-loaded]].
; settings.php (optional) : Admin menu settings that are for every question of this type. See [[Admin settings]] for info on how to add a settings page for your question type and the examples in some question types.
; amd/ : any [[Javascript_Modules|JavaScript modules]] your question type needs. (Old YUI-style JavaScript in yui/ or module.js would still work, but is not recommended.)

==Database tables==

Note that question types should only have database tables for the question definition. All runtime data is managed by the question engine.

Question definitions should use the core table <tt>question</tt>, and can use the core table <tt>question_answers</tt>. You only need to define database tables if your question definition requires extra information that cannot be stored in either of these.

==Question type and question definition classes==

===The question definition class is in question.php===

This holds the definition of a particular question of this type. For example, an object of type qtype_shortanswer_question is a short-answer question instance. If you load three short-answer questions from the question bank, then you will get three instances of that class. This class is not just the question definition, it can also track the current state of a question as a student attempts it. For example, for a multiple-choice question, the class will store what order the choices have been randomly shuffled into for that student. To put it another way, the question_definition often works with a particular question_attempt.

===The question type class is in questiontype.php===

In contrast, the question type class represents the question type. For example, the qtype_shortanswer class represents the 'short answer' type of question, and there will normally only be a single instance of this class. It has several responsiblities, including providing meta-data about this question type (e.g. public function name()). It knows how to load, save and delete questions of this type to and from the database (get_question_options and save_question_options, delete_question) and hence how to construct instances of the qtype_shortanswer_question class. It provides methods to help with editing questions of this type. It can also provide the implmentation for import and export in various formats.

==Renderer class==

Renderers are all about generating HTML output. The overall output of questions is controlled by the <tt>core_question_renderer::question(...)</tt>, which in turn calls other methods of itself, the question type renderer and the behaviour renderer, to generate the various bits of output. See [[Question_Engine_2:Overview#What_are_the_parts_of_a_question.3F|this overview of the parts of a question]].

Once again, in what follows, I only list the methods your are most likely to want to override.

===formulation_and_controls===

This displays the question text, and the controls the student will use to input their response. Some question types choose to display some feedback embedded in this area, for example ticks and crosses next to parts of the student's response.

The output code must respect the <tt>question_display_options</tt> and only reveal as much information as the calling code wants revealed. For example, the teacher creating a quiz may not want the correct answer revealed until after the quiz close date. Also, when outputting the controls, you need to respect the <tt>->readonly</tt> option.

===specific_feedback===

Anything returned by this method is included in the 'outcome' area of the question, it is some feedback that particularly relates to the response the student gave. This method is only called if the display options allow this to be shows, so you don't have to worry about testing that.

===correct_response===

This would also be included in the 'outcome' area. This should be an automatically generated (from the question definition) display of what the correct answer to the question is.

==Unit tests==

For a general introduction, see the [[PHPUnit|Moodle unit testing documentation]].

The most important parts of your question type to test are the parts of the <tt>question_definition</tt> class that process the students responses, including the compare and grade methods. The best way to start is probably to look at the tests for some of the standard question types.

Another useful type of test for questions are 'walkthrough' tests. These are implemented in using PHPunit, even though they are more integration tests than unit tests. There is [https://github.com/moodle/moodle/blob/master/question/engine/tests/helpers.php#L728 a detailed comment on the base class that explains more] and there are some nice examples in the core questions and also in the [https://github.com/moodleou/moodle-qtype_oumultiresponse/blob/master/tests/walkthrough_test.php OU Multi response github repository].

Finally, it is good to have a few Behat tests, to check that everything works end-to-end. However, since Behat is much slower than unit tests, it is best to test all the details of the grading in PHPunit.

==Manually testing a question type==

The following provides a thorough test of a new question type. A lot of the following can now be done with [[Acceptance_testing|Behat]].

# Create some new questions of your type, exercising each significantly different combination of options.
# Go back to the editing form for each question to make sure that the options were saved accurately and that you can change them and that the changes are then saved.
# Try typing invalid input into the editing form, and ensure it is rejected.
# Preview each of your new questions using a variety of question behaviours. Check the mark and feedback for a range of correct and incorrect responses.
# Add your questions to some quizzes, using a range of behaviours, and different numbers of questions per page.
# Preview those quizzes several times, entering a range of correct and incorrect responses. Note that during this testing, some useful behind-the-scenes data (e.g. question summary, the exact behaviour being used) is shown in the Technical information region, so you probably want to expand that region, and check what is going on there.
# Now log in as a student and take the quizzes for real.
# If the question type uses complex CSS or JavaScript, repeat this testing in different web browsers.
# View all of the quiz reports, and ensure that they correctly display the information about your questions.
# Backup the course, restore it as a new course, and ensure that all your questions have been copied across accurately.
# Export your questions from the original course to each of the import/export formats your support. Import these questions to a new question category, and ensure they have been copied accurately (within the limits to which your question type can be represented in each format).
# Edit the questions so that there is a link to another part of the course (e.g. a Page resource) in every place that HTML can be entered. Repeat the backup and restore test and verify that the URLs in the restored question have been updated to point to the new copy of the Page resource in the new course.
# Edit the question to add an image to every HTML field that supports it. Repeat the Editing, Preview, Backup/restore and Export/import tests, and verify that the images always work, and that you don't end up with broken image links.
# Move the category containing the questions with images to a new context in the question bank, and make sure that the image links don't break.
# Check that all the unit tests for your question type pass.
# Run code-checker (https://moodle.org/plugins/view.php?plugin=local_codechecker) over your plugin to check the coding style.
# Check your question type against Accessibility guidelines, for example the [http://www.w3.org/WAI/intro/wcag.php Web Content Accessibility Guidelines].

==See also==

Next section: [[Using_the_question_engine_from_module|Using the question engine from a module]].

* The PHP documenter comments that explain the purposes of every method in the question engine code.
* Back to [[Question_Engine_2|Question Engine 2]]

[[Category:Plugins]]

Making changes show up during development

2019-03-29T15:23:25Z

TimHunt: /* Language strings */

Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation.

== General advice ==

# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitable for development. Note that doing this will slow down your development site a bit.
# If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date.
# And then <nowiki>http://your.domain/moodle</nowiki>'''/admin/purgecaches.php''' and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated. Note there is also a CLI tool to purge caches.
# Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in the plugin's version.php, or the changes will not show up.
# You may have forgotten to run grunt.
# If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php

The above steps are a brute force approach. They will probably work, but are probably not the fastest way. Below, we list for all the various type of change you can make, the most efficient way to make the change show up.

== PHP ==

After changing the PHP files (*.php), you should just need to press reload (F5) in your browser.

=== Adding or removing an auto-loaded class ===

If you get class-not-found errors, you need to visit <nowiki>http://your.domain/moodle</nowiki>'''/admin'''.

== JavaScript ==

After editing the [[Javascript Modules]] source files (amd/src/*.js), if you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser.

If JS caching is on, you need to re-run grunt. (Do you also need to purge a cache??? I don't think so.)

== CSS ==

After changing the CSS styles (*.css) ...

== SCSS ==

After changing SCSS (*.scss) files ...

== LESS ==

After changing LESS (*.less) files ...

== Language strings ==

After changing language pack strings (lang/en/type_plugin.php):

* The best option is to turn off Admin -> Language -> Language settings -> Cache all language strings when doing development. Then you only need to press F5 to refresh to see your changes.
* Otherwise you need to Purge all caches (or just the Language strings cache) before reloading.

== Capabilities ==

After changing capabilities (db/access.php) ...

== Scheduled tasks ==

After changing scheduled tasks (db/tasks.php) you need to

# Bump the plugin version number.
# Go to admin -> Notifications.

Then check that the task shows up on Admin -> Server -> Scheduled tasks.

== Web services ==

After changing web services (db/services.php) ...

== Database structure ==

After changing the database scheme (db/install.xml, db/upgrade.php) ...

== PHPunit ==

== Behat ==

After you add a new *.feature file, you need to re-run

$ php admin/tool/behat/cli/init.php

== Mobile support for plugins ==

If you are doing the kind of development described in [[Mobile support for plugins]], using a pre-built version of the app like https://mobileapp.moodledemo.net/.

Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them.

=== General note ===

If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart.

# In browser developer tools, go to Application -> Clear storage.
# Close the browser, and re-launch.

===Adding mobile support to a plugin for the first time===

# Bump the plugin version number.
# Go to admin -> Notifications.
# F5 in the app to restart.

=== HTML template ===

After changing an existing template (mobile/*.html), just pull down in the app to refresh.

=== Client-side JavaScript ===

After changing an existing client-side JavaScript (mobile/*.js), press F5 in the browser developer tools to restart the app.

=== Server-side classes/output/mobile.php ===

???

=== Mobile CSS ===

# Bump version number in db/mobile.php
# Purge caches (specifically the tool_mobile/plugininfo MUC cache)
# Press F5 to restart the app.

Making changes show up during development

2019-03-29T15:18:06Z

TimHunt: /* Scheduled tasks */

Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation.

== General advice ==

# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitable for development. Note that doing this will slow down your development site a bit.
# If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date.
# And then <nowiki>http://your.domain/moodle</nowiki>'''/admin/purgecaches.php''' and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated. Note there is also a CLI tool to purge caches.
# Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in the plugin's version.php, or the changes will not show up.
# You may have forgotten to run grunt.
# If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php

The above steps are a brute force approach. They will probably work, but are probably not the fastest way. Below, we list for all the various type of change you can make, the most efficient way to make the change show up.

== PHP ==

After changing the PHP files (*.php), you should just need to press reload (F5) in your browser.

=== Adding or removing an auto-loaded class ===

If you get class-not-found errors, you need to visit <nowiki>http://your.domain/moodle</nowiki>'''/admin'''.

== JavaScript ==

After editing the [[Javascript Modules]] source files (amd/src/*.js), if you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser.

If JS caching is on, you need to re-run grunt. (Do you also need to purge a cache??? I don't think so.)

== CSS ==

After changing the CSS styles (*.css) ...

== SCSS ==

After changing SCSS (*.scss) files ...

== LESS ==

After changing LESS (*.less) files ...

== Language strings ==

After changing language pack strings (lang/en/type_plugin.php) ...

== Capabilities ==

After changing capabilities (db/access.php) ...

== Scheduled tasks ==

After changing scheduled tasks (db/tasks.php) you need to

# Bump the plugin version number.
# Go to admin -> Notifications.

Then check that the task shows up on Admin -> Server -> Scheduled tasks.

== Web services ==

After changing web services (db/services.php) ...

== Database structure ==

After changing the database scheme (db/install.xml, db/upgrade.php) ...

== PHPunit ==

== Behat ==

After you add a new *.feature file, you need to re-run

$ php admin/tool/behat/cli/init.php

== Mobile support for plugins ==

If you are doing the kind of development described in [[Mobile support for plugins]], using a pre-built version of the app like https://mobileapp.moodledemo.net/.

Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them.

=== General note ===

If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart.

# In browser developer tools, go to Application -> Clear storage.
# Close the browser, and re-launch.

===Adding mobile support to a plugin for the first time===

# Bump the plugin version number.
# Go to admin -> Notifications.
# F5 in the app to restart.

=== HTML template ===

After changing an existing template (mobile/*.html), just pull down in the app to refresh.

=== Client-side JavaScript ===

After changing an existing client-side JavaScript (mobile/*.js), press F5 in the browser developer tools to restart the app.

=== Server-side classes/output/mobile.php ===

???

=== Mobile CSS ===

# Bump version number in db/mobile.php
# Purge caches (specifically the tool_mobile/plugininfo MUC cache)
# Press F5 to restart the app.

Moodle App Plugins Development Guide

2019-03-27T14:36:50Z

TimHunt: /* Step 1. Update the db/mobile.php file */

{{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. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']).
: Please only include the strings you acutally 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.

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

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

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

Making changes show up during development

2019-03-26T16:43:56Z

TimHunt: TimHunt moved page Making changes show up during Moodle development to Making changes show up during development without leaving a redirect

Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation.

However, this page is still quite new, so please help build it.

==General advice==

# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitalble for development. (But note that doing this will slow down your development site.
# If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date.
# And then <nowiki>http://your.domain/moodle</nowiki>'''/vle/admin/purgecaches.php''' and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated.
# Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in version.php, or the changes will not show up.
# You may have forgotted to run grunt.
# If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php.

The above steps are a brute force approach. They will probably work, but are probably not the fastest way. Below, we list for all the various type of change you can make, the most efficient way to make the change show up.

==Changes in the Moodle and Moodle plugins==

===Changing PHP (*.php)===

You should just need to press reload (F5) in your browser.

===Adding or removing an auto-loaded class===

If you get class-not-found errors, you need to visit <nowiki>http://your.domain/moodle</nowiki>'''/admin'''.

===Changing JavaScript (amd/src/*.js)===

If you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser.

If JS caching is on, you need to re-run grunt. (Do you also need to purge a cache??? I don't think so.)

===Changing CSS (*.css)===

===Changing SCSS/LESS (*.scss/*.less)===

===Changing language strings (lang/en/type_plugin.php)===

===Changing capabilities (db/access.php)===

===Changing scheduled tasks (db/tasks.php)===

===Changing web services (db/services.php)===

===Changing database strucutre (db/install.xml, db/upgrade.php)===

===Adding a new PHPunit test===

===Adding a new Behat test===

You need to re-run

php admin/tool/behat/cli/init.php

or any newly-added *.feature file will not be found.

==Changes in mobile support for plugins==

If you are doing the kind of development descrived in [[Mobile support for plugins]], using a pre-built version of the app like https://mobileapp.moodledemo.net/.

Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them.

===General note it you are seeing a lot of errors===

If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart.

# In browser developer tools, go to Application -> Clear storage.
# Close the browser, and re-launch.

===Adding mobile support to a plugin for the first time===

# Bump the plugin version number.
# Go to admin -> Notifications.
# F5 in the app to restart.

===Change in existing template (mobile/*.html)===

Just pull down in the app to refresh.

===Adding a new template (mobile/*.html)===

???

===Change to existing client-side JavaScript (mobile/*.js)

Press F5 in the browser developer tools to restart the app.

===New client-side JavaScript (mobile/*.js)

===Change to server-side classes/output/mobile.php - ???

===Changing CSS===

# bump version number in db/mobile.php
# purge caches (specifically the tool_mobile/plugininfo MUC cache)
# Press F5 to restart the app.

==Changes in the Moodle mobile app==

TODO.

Making changes show up during development

2019-03-26T16:27:17Z

TimHunt: /* Changing web services (db/services.php) */

Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation.

However, this page is still quite new, so please help build it.

==General advice==

# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitalble for development. (But note that doing this will slow down your development site.
# If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date.
# And then <nowiki>http://your.domain/moodle</nowiki>'''/vle/admin/purgecaches.php''' and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated.
# Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in version.php, or the changes will not show up.
# You may have forgotted to run grunt.
# If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php.

The above steps are a brute force approach. They will probably work, but are probably not the fastest way. Below, we list for all the various type of change you can make, the most efficient way to make the change show up.

==Changes in the Moodle and Moodle plugins==

===Changing PHP (*.php)===

You should just need to press reload (F5) in your browser.

===Adding or removing an auto-loaded class===

If you get class-not-found errors, you need to visit <nowiki>http://your.domain/moodle</nowiki>'''/admin'''.

===Changing JavaScript (amd/src/*.js)===

If you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser.

If JS caching is on, you need to re-run grunt. (Do you also need to purge a cache??? I don't think so.)

===Changing CSS (*.css)===

===Changing SCSS/LESS (*.scss/*.less)===

===Changing language strings (lang/en/type_plugin.php)===

===Changing capabilities (db/access.php)===

===Changing scheduled tasks (db/tasks.php)===

===Changing web services (db/services.php)===

===Changing database strucutre (db/install.xml, db/upgrade.php)===

===Adding a new PHPunit test===

===Adding a new Behat test===

You need to re-run

php admin/tool/behat/cli/init.php

or any newly-added *.feature file will not be found.

==Changes in mobile support for plugins==

If you are doing the kind of development descrived in [[Mobile support for plugins]], using a pre-built version of the app like https://mobileapp.moodledemo.net/.

Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them.

===General note it you are seeing a lot of errors===

If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart.

# In browser developer tools, go to Application -> Clear storage.
# Close the browser, and re-launch.

===Adding mobile support to a plugin for the first time===

# Bump the plugin version number.
# Go to admin -> Notifications.
# F5 in the app to restart.

===Change in existing template (mobile/*.html)===

Just pull down in the app to refresh.

===Adding a new template (mobile/*.html)===

???

===Change to existing client-side JavaScript (mobile/*.js)

Press F5 in the browser developer tools to restart the app.

===New client-side JavaScript (mobile/*.js)

===Change to server-side classes/output/mobile.php - ???

===Changing CSS===

# bump version number in db/mobile.php
# purge caches (specifically the tool_mobile/plugininfo MUC cache)
# Press F5 to restart the app.

==Changes in the Moodle mobile app==

TODO.

Making changes show up during development

2019-03-26T16:26:39Z

TimHunt: Created page with "Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all..."

Sometime, when you are trying to do Moodle development, you edit the code, and nothing seems to change as a result. This is because, to improve performance, Moodle now has all sorts of caching built in. When this is happening, this page will try to give you the quickest way to make your changes show up in all situation.

However, this page is still quite new, so please help build it.

==General advice==

# In your development site, change most of the admin settings like 'Cache language strings', 'Cache JavaScript' to be suitalble for development. (But note that doing this will slow down your development site.
# If in doubt, visit <nowiki>http://your.domain/moodle</nowiki>'''/admin''' to check that the Moodle install is up-to-date.
# And then <nowiki>http://your.domain/moodle</nowiki>'''/vle/admin/purgecaches.php''' and click the 'Purge all caches' button. This will slow things down for the next few requests, until the caches have re-populated.
# Depending on what you changed in your plugin, then in addition to the above, you may need to remember to increase the version number in version.php, or the changes will not show up.
# You may have forgotted to run grunt.
# If you have just added a new Behat or PHPunit test, you may need to re-run admin/tool/.../cli/init.php.

The above steps are a brute force approach. They will probably work, but are probably not the fastest way. Below, we list for all the various type of change you can make, the most efficient way to make the change show up.

==Changes in the Moodle and Moodle plugins==

===Changing PHP (*.php)===

You should just need to press reload (F5) in your browser.

===Adding or removing an auto-loaded class===

If you get class-not-found errors, you need to visit <nowiki>http://your.domain/moodle</nowiki>'''/admin'''.

===Changing JavaScript (amd/src/*.js)===

If you have Administration -> Appearance -> AJAX and Javascript -> Cache Javascript turned off, then you should just need to reload (F5) in your browser.

If JS caching is on, you need to re-run grunt. (Do you also need to purge a cache??? I don't think so.)

===Changing CSS (*.css)===

===Changing SCSS/LESS (*.scss/*.less)===

===Changing language strings (lang/en/type_plugin.php)===

===Changing capabilities (db/access.php)===

===Changing scheduled tasks (db/tasks.php)===

===Changing web services (db/services.php)===

===Changing database strucutre (db/install.xml, db/upgrade.php)

===Adding a new PHPunit test===

===Adding a new Behat test===

You need to re-run

php admin/tool/behat/cli/init.php

or any newly-added *.feature file will not be found.

==Changes in mobile support for plugins==

If you are doing the kind of development descrived in [[Mobile support for plugins]], using a pre-built version of the app like https://mobileapp.moodledemo.net/.

Note, these steps were originally written by people mostly on question type plugins. Hopefully they are generally applicable, but if they don't make sense in your case, that might be why. Please edit to improve them.

===General note it you are seeing a lot of errors===

If there are lots of red error messages appearing in the JavaScript console (but not the very common error 'ERROR Error: Uncaught (in promise): null...' that repeats every minute and fills the console logs!) it is often necessary to clear site data and restart.

# In browser developer tools, go to Application -> Clear storage.
# Close the browser, and re-launch.

===Adding mobile support to a plugin for the first time===

# Bump the plugin version number.
# Go to admin -> Notifications.
# F5 in the app to restart.

===Change in existing template (mobile/*.html)===

Just pull down in the app to refresh.

===Adding a new template (mobile/*.html)===

???

===Change to existing client-side JavaScript (mobile/*.js)

Press F5 in the browser developer tools to restart the app.

===New client-side JavaScript (mobile/*.js)

===Change to server-side classes/output/mobile.php - ???

===Changing CSS===

# bump version number in db/mobile.php
# purge caches (specifically the tool_mobile/plugininfo MUC cache)
# Press F5 to restart the app.

==Changes in the Moodle mobile app==

TODO.

Acceptance testing for the Moodle App

2019-03-26T15:52:13Z

TimHunt: /* Useful tips */

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. (Note it is best to checked out the integration branch, as master branch does not create config.json at the moment - March 2019).

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

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.0

* 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. There are several ways to run the Ionic app and you will want to use the configuration for the way that you prefer.

Broadly speaking the options are:
# Manage the Ionic app yourself
# Have Behat control the lifecycle (start/stop) of the ionic app

The recommended option is to launch the App yourself using Docker.

==== Manually launch the app environment yourself ====

When manually launching the app yourself, you will be responsible for starting the App before Behat starts, and stopping it when you finish your testing.

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.

To use this method then you need to add the following line to config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

There are two ways to run the app yourself:
# Using Docker
# Launching ionic yourself

===== Using Docker (Recommended) =====

If you are using the Docker image, you just need to start the Docker container:

<code>
docker run -p 8100:8100 moodlehq/moodlemobile2
</code>

===== Using a local installation =====

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>

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you need to add the following line to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

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

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

== 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 specify them using the 'aria-label' attribute. You can find the value using the Chrome inspector. (Note that if you cannot locate the thing to click using on-screen text or an aria-lable, then this is often a sign that you have an accessibility bug that should be fixed.)

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. (Again, having two buttons that are indestinguishable to Behat is probably an indication of an accessibility bug.)
* 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, or look at the source in [https://github.com/moodle/moodle/blob/master/lib/tests/behat/app_behat_runtime.js lib/tests/behat/app_behat_runtime.js].

==Useful tips==

# Make sure you added $CFG->behat_ionic_wwwroot = 'http://localhost:8100'; to your config.php.
# It seems that the Mobile behat tests do not like xdebug, so I turn that off in php.ini while running the tests. (Remeber to restart Apache after that.)
# Remember when you need to re-run php admin/tool/behat/cli/init.php from your development code base root. Make sure the message 'Configured app tests for version 3.6.1' (or whatever version) appears.
# Currently (2019-03-26) things break if you try to use the master branch of the app. (One symptom is missing language strings). You need to checkout the 'integration' branch.
# The message 'cURL request for "http://localhost:8100/config.json" failed with: Failed to connect to localhost port 8100: Connection refused' means that you have not started the ionic server, or have not waited long enough (several minutes) for it to start).
# Message 'missing config.json' - this should exist in your app code base/www, just re-run ionic serve -b to re-create it.
# Message 'Error The plugins required by this course could not be loaded correctly...' - means either some activity on the course is not converted to moodle mobile app plugin or there is a timeout in the request to your behat site. To clear the timeout message go to mobile site in unsafe browser (localhost:8100), open the Inspector, open the Application tab, select Clear storage, press Clear site data, close Inspector, close the tab with mobile site, re-open mobile site in new tab and log in, then in a separate tab log in to your behat site 127.0.0.1/moodle as student1/student1 and make sure you can get into course 1 without the silly error.
# Message 'Fatal error: Maximum execution time of 30 seconds exceeded in...' - your local site has not been updated/visited since an upgrade. Just go to your local behat site (127.0.0.1/moodle or see your address in config.php), log in as admin and run notifications (admin/), then visit a course. Do this step often to avoid timeouts!
# Create an unsafe browser link on your desktop. That is, a shortcut with a command like "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content"

Acceptance testing for the Moodle App

2019-03-26T15:51:44Z

TimHunt:

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. (Note it is best to checked out the integration branch, as master branch does not create config.json at the moment - March 2019).

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

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.0

* 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. There are several ways to run the Ionic app and you will want to use the configuration for the way that you prefer.

Broadly speaking the options are:
# Manage the Ionic app yourself
# Have Behat control the lifecycle (start/stop) of the ionic app

The recommended option is to launch the App yourself using Docker.

==== Manually launch the app environment yourself ====

When manually launching the app yourself, you will be responsible for starting the App before Behat starts, and stopping it when you finish your testing.

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.

To use this method then you need to add the following line to config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

There are two ways to run the app yourself:
# Using Docker
# Launching ionic yourself

===== Using Docker (Recommended) =====

If you are using the Docker image, you just need to start the Docker container:

<code>
docker run -p 8100:8100 moodlehq/moodlemobile2
</code>

===== Using a local installation =====

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>

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you need to add the following line to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

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

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

== 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 specify them using the 'aria-label' attribute. You can find the value using the Chrome inspector. (Note that if you cannot locate the thing to click using on-screen text or an aria-lable, then this is often a sign that you have an accessibility bug that should be fixed.)

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. (Again, having two buttons that are indestinguishable to Behat is probably an indication of an accessibility bug.)
* 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, or look at the source in [https://github.com/moodle/moodle/blob/master/lib/tests/behat/app_behat_runtime.js lib/tests/behat/app_behat_runtime.js].

===Useful tips===

# Make sure you added $CFG->behat_ionic_wwwroot = 'http://localhost:8100'; to your config.php.
# It seems that the Mobile behat tests do not like xdebug, so I turn that off in php.ini while running the tests. (Remeber to restart Apache after that.)
# Remember when you need to re-run php admin/tool/behat/cli/init.php from your development code base root. Make sure the message 'Configured app tests for version 3.6.1' (or whatever version) appears.
# Currently (2019-03-26) things break if you try to use the master branch of the app. (One symptom is missing language strings). You need to checkout the 'integration' branch.
# The message 'cURL request for "http://localhost:8100/config.json" failed with: Failed to connect to localhost port 8100: Connection refused' means that you have not started the ionic server, or have not waited long enough (several minutes) for it to start).
# Message 'missing config.json' - this should exist in your app code base/www, just re-run ionic serve -b to re-create it.
# Message 'Error The plugins required by this course could not be loaded correctly...' - means either some activity on the course is not converted to moodle mobile app plugin or there is a timeout in the request to your behat site. To clear the timeout message go to mobile site in unsafe browser (localhost:8100), open the Inspector, open the Application tab, select Clear storage, press Clear site data, close Inspector, close the tab with mobile site, re-open mobile site in new tab and log in, then in a separate tab log in to your behat site 127.0.0.1/moodle as student1/student1 and make sure you can get into course 1 without the silly error.
# Message 'Fatal error: Maximum execution time of 30 seconds exceeded in...' - your local site has not been updated/visited since an upgrade. Just go to your local behat site (127.0.0.1/moodle or see your address in config.php), log in as admin and run notifications (admin/), then visit a course. Do this step often to avoid timeouts!
# Create an unsafe browser link on your desktop. That is, a shortcut with a command like "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content"

Setting up your development environment for the Moodle App

2019-03-26T12:05:30Z

TimHunt: /* Setup the environment */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==

The structure of this page is
* the first part, up to the point where you get the 'ionic serve' command to work is what you need to be able to do development on the app and test it in a browser.
* the second part is about how to buld a version of the app that can be run on a device.
* then at the end is a list of troubleshooting advice. If you encouter a problem that is not already listed, please consider adding it.

The majority of your development will be done using a browser. You will probably on begin to use an emulator once you need to simulate a real mobile device.

If you are just [[Mobile support for plugins|adding mobile support to plugins]], remember that most of your development can be done using the online pre-built version at https://mobileapp.moodledemo.net/ (with Chrome or Chromium). However, if you want to be able to to write [[Acceptance_testing_for_the_mobile_app|automated acceptance tests for the app]] then you need to follow this page at least as far as getting the ionic serve command to work on this page.

== Requirements ==

Windows tip: ingore any use of the sudo command below. Just use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same nvm commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors. You only really need <tt>cordova prepare</tt> to work if you are going to go on and build the app.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

Congratulations! Now that you have got to the piont where the 'ionic serve' command works, you can start doing development on the app. You only need to read the rest of the page if you want to build packaged versions of the app.

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

According to Google, this happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. It's weird that the installation process does that, it should create the platform with the right name unless it was changed manually.

The solution seems to be removing and adding the iOS platform again:

ionic platform remove ios
ionic platform add ios

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

The ''cordova-plugin-file'' version specified in config.xml is 6.0.1, for some reason the installation process installed a wrong version for that plugin. You can manually install the ''cordova-plugin-file'' plugin like this:

cordova plugin remove cordova-plugin-file
cordova plugin add cordova-plugin-file@6.0.1

Please notice that if there is any plugin installed that depends on ''cordova-plugin-file'' you'll have to remove and re-add them too.

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-26T12:04:36Z

TimHunt: /* Overview */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==

The structure of this page is
* the first part, up to the point where you get the 'ionic serve' command to work is what you need to be able to do development on the app and test it in a browser.
* the second part is about how to buld a version of the app that can be run on a device.
* then at the end is a list of troubleshooting advice. If you encouter a problem that is not already listed, please consider adding it.

The majority of your development will be done using a browser. You will probably on begin to use an emulator once you need to simulate a real mobile device.

If you are just [[Mobile support for plugins|adding mobile support to plugins]], remember that most of your development can be done using the online pre-built version at https://mobileapp.moodledemo.net/ (with Chrome or Chromium). However, if you want to be able to to write [[Acceptance_testing_for_the_mobile_app|automated acceptance tests for the app]] then you need to follow this page at least as far as getting the ionic serve command to work on this page.

== Requirements ==

Windows tip: ingore any use of the sudo command below. Just use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same nvm commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

Congratulations! Now that you have got to the piont where the 'ionic serve' command works, you can start doing development on the app. You only need to read the rest of the page if you want to build packaged versions of the app.

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

According to Google, this happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. It's weird that the installation process does that, it should create the platform with the right name unless it was changed manually.

The solution seems to be removing and adding the iOS platform again:

ionic platform remove ios
ionic platform add ios

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

The ''cordova-plugin-file'' version specified in config.xml is 6.0.1, for some reason the installation process installed a wrong version for that plugin. You can manually install the ''cordova-plugin-file'' plugin like this:

cordova plugin remove cordova-plugin-file
cordova plugin add cordova-plugin-file@6.0.1

Please notice that if there is any plugin installed that depends on ''cordova-plugin-file'' you'll have to remove and re-add them too.

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-26T11:57:07Z

TimHunt: /* Open the app in the browser */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Just use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same nvm commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node directly, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

Congratulations! Now that you have got to the piont where the 'ionic serve' command works, you can start doing development on the app. You only need to read the rest of the page if you want to build packaged versions of the app.

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

According to Google, this happens when you create the iOS platform with a certain <name> and then you change that name in config.xml. It's weird that the installation process does that, it should create the platform with the right name unless it was changed manually.

The solution seems to be removing and adding the iOS platform again:

ionic platform remove ios
ionic platform add ios

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

The ''cordova-plugin-file'' version specified in config.xml is 6.0.1, for some reason the installation process installed a wrong version for that plugin. You can manually install the ''cordova-plugin-file'' plugin like this:

cordova plugin remove cordova-plugin-file
cordova plugin add cordova-plugin-file@6.0.1

Please notice that if there is any plugin installed that depends on ''cordova-plugin-file'' you'll have to remove and re-add them too.

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

== See also ==

http://ionicframework.com/docs/cli/

Acceptance testing for the Moodle App

2019-03-26T11:40:58Z

TimHunt: /* Debugging tests */

Acceptance testing for the Moodle App

2019-03-26T11:32:04Z

TimHunt: /* Actions */

Acceptance testing for the Moodle App

2019-03-26T11:30:16Z

TimHunt: /* Actions */

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. (Note it is best to checked out the integration branch, as master branch does not create config.json at the moment - March 2019).

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

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.0

* 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. There are several ways to run the Ionic app and you will want to use the configuration for the way that you prefer.

Broadly speaking the options are:
# Manage the Ionic app yourself
# Have Behat control the lifecycle (start/stop) of the ionic app

The recommended option is to launch the App yourself using Docker.

==== Manually launch the app environment yourself ====

When manually launching the app yourself, you will be responsible for starting the App before Behat starts, and stopping it when you finish your testing.

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.

To use this method then you need to add the following line to config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

There are two ways to run the app yourself:
# Using Docker
# Launching ionic yourself

===== Using Docker (Recommended) =====

If you are using the Docker image, you just need to start the Docker container:

<code>
docker run -p 8100:8100 moodlehq/moodlemobile2
</code>

===== Using a local installation =====

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>

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you need to add the following line to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

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

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

== 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 specify them using the 'aria-label' attribute. You can find the value using the Chrome inspector. (Note that if you cannot locate the thing to click using on-screen text or an aria-lable, then this is often a sign that you have an accessibility bug that should be fixed.)

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-03-26T11:19:32Z

TimHunt: /* Using a local installation = */

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. (Note it is best to checked out the integration branch, as master branch does not create config.json at the moment - March 2019).

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

docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.0

* 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. There are several ways to run the Ionic app and you will want to use the configuration for the way that you prefer.

Broadly speaking the options are:
# Manage the Ionic app yourself
# Have Behat control the lifecycle (start/stop) of the ionic app

The recommended option is to launch the App yourself using Docker.

==== Manually launch the app environment yourself ====

When manually launching the app yourself, you will be responsible for starting the App before Behat starts, and stopping it when you finish your testing.

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.

To use this method then you need to add the following line to config.php:

<code php>
$CFG->behat_ionic_wwwroot = 'http://localhost:8100';
</code>

There are two ways to run the app yourself:
# Using Docker
# Launching ionic yourself

===== Using Docker (Recommended) =====

If you are using the Docker image, you just need to start the Docker container:

<code>
docker run -p 8100:8100 moodlehq/moodlemobile2
</code>

===== Using a local installation =====

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>

==== Let Behat launch the app environment ====

If you want Behat to launch the app environment for you, then you need to add the following line to config.php. This only works if you installed the app development environment locally, not if you are using Docker.

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

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

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

Setting up your development environment for the Moodle App

2019-03-25T19:37:15Z

TimHunt: /* Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0". */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

I was getting this from <tt>cordova prepare</tt>. I have no idea why. Please help!

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

I get this when I try to run <tt>cordova prepare</tt>. I have no idea why. Please help!

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:37:04Z

TimHunt: /* The product name change ( tag) in config.xml is not supported dynamically */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

I was getting this from <tt>cordova prepare</tt>. I have no idea why. Please help!

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app if you run gulp after <tt>npm run setup</tt> has failed with this error.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

I get this when I try to run <tt>cordova prepare</tt>. I have no idea why. Please help!

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:36:08Z

TimHunt: /* The product name change ( tag) in config.xml is not supported dynamically */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

I was getting this from <tt>cordova prepare</tt>. I have no idea why. Please help!

Note that this does not seem to prevent <tt>ionic --serve</tt> from serving a working app.

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

I get this when I try to run <tt>cordova prepare</tt>. I have no idea why. Please help!

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:30:31Z

TimHunt: /* Strange NPM errors */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

To get more debug output from npm commands, see https://docs.npmjs.com/misc/config#shorthands-and-other-cli-niceties. In particular try adding <tt>--loglevel verbose</tt> (or <tt>--loglevel info</tt> or <tt>--loglevel silly</tt>) to the command-line.

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

I was getting this from <tt>cordova prepare</tt>. I have no idea why. Please help!

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

I get this when I try to run <tt>cordova prepare</tt>. I have no idea why. Please help!

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:22:24Z

TimHunt: /* Troubleshooting */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Strange NPM errors ===

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

===Unhandled rejection Error: Command failed: C:\cygwin64\bin\git.EXE ...===

You need to heed the advice at https://www.npmjs.com/package/npm#installing-on-cygwin. Cygwin users are not welcome in the Node world. 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 mobile development. (You don't need your Cygwin bin folder on the Windows path. 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===

I was getting this from <tt>cordova prepare</tt>. I have no idea why. Please help!

===Failed to install 'cordova-plugin-file-transfer': CordovaError: Version of installed plugin: "cordova-plugin-file@4.3.3" does not satisfy dependency plugin requirement "cordova-plugin-file@>=5.0.0".===

I get this when I try to run <tt>cordova prepare</tt>. I have no idea why. Please help!

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:11:17Z

TimHunt: /* Install Node.js */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions, for example https://github.com/coreybutler/nvm-windows/issues/58#issuecomment-272608696.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:10:42Z

TimHunt: /* ReferenceError: internalBinding is not defined */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

=== npm update check failed===

I got the error

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

on Windows because I installed too much as admin, and the suggested command does not work on Windows. The is to manually check the ownership of all the files in C:\Users\username\.config\configstore. In my case it was update-notifier-npm.json which got changed to be owned by Administrator.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:02:52Z

TimHunt: /* Open the app in the browser */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium # or chrome or whatever browser.

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T19:02:00Z

TimHunt: /* Requirements */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

Windows tip: ingore any use of the sudo command below. Jsut use the command without it. Most things work that way, and if they don't try in a Powershell window that you have opened with 'Run as administrator ...'.

===Install a browser for development===

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

===Install git===

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

===Install Node.js===

On Linux we recommend you use [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

nvm install latest
nvm use 11.12.0 # Or whatever number nvm install reported.

(Exact version is probably not critical. Moodle HQ devs report using both 8.12.x and 11.12.0 as of 2019-03-25.)

On Windows we recommend you use https://github.com/coreybutler/nvm-windows. Same mvn commands as for Linux.

On Mac users we recommend to install NodeJS via Macports.

(It may seem simpler and easier to install directly from http://nodejs.org, but actually it seems to me more tricky to get that to work. If you have previously installed Node direclty, and want to switch to nvm, you need to un-install node completely before installing nvm - or Google for trouble-shooting instructions.)

===Install ionic===
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

===Install the npm required packages===
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

===Windows only: Native build dependencies===

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

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

Phonegap plugin push 1.9.0 requires CocoaPods to work on a Mac. The installation steps can be found in https://cocoapods.org/

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T18:42:14Z

TimHunt: /* Setup the environment */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

'''Install a browser for development'''

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

'''Install git'''

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

'''Install Node.js'''

http://nodejs.org

For Mac users we recommend to install NodeJS via Macports.

On Ubuntu you may be best off installing Node via [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

'''Install ionic:'''
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

'''Install the npm required packages'''
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

'''Native build dependencies for Windows'''

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

'''Push notifications for Mac'''

Phonegap plugin push 1.9.0 requires CocoaPods to work. The installation steps can be found in https://cocoapods.org/

E.g. in Mac OS X you have to run:

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp</tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for the Moodle App

2019-03-25T18:42:02Z

TimHunt: /* Setup the environment */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

Note: These instructions do work (give or take) for the current 3.5.x version of the Moodle Mobile app.

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

Remember that the majority of your development can be done using the online version https://mobileapp.moodledemo.net/ (requires Chrome or Chromium browser) as indicated in [[Mobile support for plugins]]

== Requirements ==

'''Install a browser for development'''

We recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read [[Moodle_Mobile_development_using_Chrome_or_Chromium]] for more information

'''Install git'''

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

'''Install Node.js'''

http://nodejs.org

For Mac users we recommend to install NodeJS via Macports.

On Ubuntu you may be best off installing Node via [https://github.com/creationix/nvm nvm] - this lets you switch Node versions, and makes the install a bit easier than the official installation route.

'''Install ionic:'''
npm cache clean
npm install -g cordova ionic # (If it throws an EACCESS error, run it again with sudo)

'''Install the npm required packages'''
sudo npm install -g gulp # (This will install gulp in a folder that should be in the PATH)

'''Native build dependencies for Windows'''

node-gyp 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 not]), on Windows, run the following command as administrator (in cmd or Powershell):

npm install --global --production windows-build-tools

'''Push notifications for Mac'''

Phonegap plugin push 1.9.0 requires CocoaPods to work. The installation steps can be found in https://cocoapods.org/

E.g. in Mac OS X you have to run:

sudo gem install cocoapods
pod setup

Please note that for compiling the app in Mac you need to open the .xcworkspace file, more information here: MOBILE-1970

== Clone the app base code ==

Clone the code base into a local directory in your computer.
It may be an idea to work from the integration branch rather than master.
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory
git checkout integration

== Setup the environment ==

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json and /config.xml files and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

The following command must be run in the project's root folder:
npm run setup

If this fails, you can see what it is doing by looking at the 'scripts' section in package.json. At the moment it is doing <tt>npm install && cordova prepare && gulp<\tt>. That is, running three commands back-to-back, but only carrying on if the previous one succeeds completely. You can try running the three commands separately. If you do, <tt>ionic serve</tt> (see below) may work, even if <tt>cordova prepare</tt> gives errors.

== Open the app in the browser ==
First start Chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium

If you don't want to open any browser you should run:

ionic serve -b

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

Update project platforms:

ionic cordova platform remove android
ionic cordova platform remove ios
ionic cordova platform add android
ionic cordova platform add ios

== Updating plugins ==

cordova plugin remove your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see the guides below to be able to build for Android and iOS using the command line:

Android: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

iOS: https://cordova.apache.org/docs/en/latest/guide/platforms/ios/index.html

If the build fails, please run <code>cordova requirements</code> to check that you fulfilled all requirements for the platform.

If you get errors while building, please see the Troubleshooting section below.

If using '''Ubuntu''' you should install the packages: gradle and libgradle-android-plugin-java (and all its dependencies) to build.

== Compiling using AOT ==

Angular has 2 ways of compiling: JIT and AOT. Running "ionic serve" or "ionic build" compiles using JIT by default, which is faster to compile but the app takes longer to start.

When building for release you should always compile using AOT, otherwise the app can take too long to start in some devices. The default AOT compiling causes some issues with the database activity and the [[Mobile support for plugins]], so you have to modify a couple of files in order to make this work.

First you need to open the file: ''node_modules/@angular/platform-browser-dynamic/esm5/platform-browser-dynamic.js''. Search the variable called "''_NO_RESOURCE_LOADER''", you'll see it has a function named "''get''" with this line:

<code javascript>
throw new Error("No ResourceLoader implementation has been provided. Can't read the url \"" + url + "\"");</code>

Remove that line and put this code instead:

<code javascript>
url = 'templates/' + url;

var resolve;
var reject;
var promise = new Promise(function (res, rej) {
resolve = res;
reject = rej;
});
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'text';
xhr.onload = function () {
// responseText is the old-school way of retrieving response (supported by IE8 & 9)
// response/responseType properties were introduced in ResourceLoader Level2 spec (supported by IE10)
var response = xhr.response || xhr.responseText;
// normalize IE9 bug (http://bugs.jquery.com/ticket/1450)
var status = xhr.status === 1223 ? 204 : xhr.status;
// fix status code when it is 0 (0 status is undocumented).
// Occurs when accessing file resources or on Android 4.1 stock browser
// while retrieving files from application cache.
if (status === 0) {
status = response ? 200 : 0;
}
if (200 <= status && status <= 300) {
resolve(response);
}
else {
reject("Failed to load " + url);
}
};
xhr.onerror = function () { reject("Failed to load " + url); };
xhr.send();
return promise;
</code>

We tried to replace the default loader with our own implementation, but we weren't able to make the compiler work so the only solution left was to modify the default one.

Now you need to open the file: ''node_modules/@ionic/app-scripts/dist/util/config.js''. In that file you need to remove the ''context.isProd'' condition from the options ''runMinifyJs'' and ''optimizeJs''. So the final code for that part should be like this:

<code javascript>
context.runMinifyJs = [
context.runMinifyJs,
hasArg('--minifyJs')
].find(function (val) { return typeof val === 'boolean'; });
context.runMinifyCss = [
context.runMinifyCss,
context.isProd || hasArg('--minifyCss')
].find(function (val) { return typeof val === 'boolean'; });
context.optimizeJs = [
context.optimizeJs,
hasArg('--optimizeJs')
].find(function (val) { return typeof val === 'boolean'; });
</code>

We want to compile in production mode but without optimizing and minifying Javascript because that breaks our plugins support. However, Ionic doesn't let you do that, so the only option is to do this change.

With these changes done you can now compile using production mode:

<code php>
npm run ionic:build -- --prod</code>

This command will generate the app files and put them inside ''www'' folder. If you now want to install that app in a real device you can run "''cordova run android''" or "''cordova build ios''" (please don't use "''ionic cordova ...''" or "''ionic serve''" because it will override your build files!).

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

=== com.android.dex.DexException: Multiple dex files define XXX ===
Open the file ''platforms/android/build.gradle'' and add this code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

=== 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 ''platforms/android/build.gradle'' and add this code at the end:

configurations.all {
resolutionStrategy.force 'com.android.support:support-v4:24.0.0'
}

=== ERROR: In <declare-styleable> FontFamilyFont, unable to find attribute android:font ===

Open the file ''platforms/android/build.gradle'' and add this code at the end:

android {
compileSdkVersion 26
buildToolsVersion "26.0.1"
}

=== Error: Could not find gradle wrapper within Android SDK. Might need to update your Android SDK. ===

1. Download Android studio - https://developer.android.com/studio/

2. Copy the folder android-studio/plugins/android/lib/templates

3. Paste in the folder android-sdk-folder/Sdk/tools

=== Could not find com.android.support:support-v4:27.1.0 ===

Open the file ''platforms/android/build.gradle'' and configure like this:

allprojects {
repositories {
jcenter()
maven {
url "https://maven.google.com"
}
}
}

=== Error: not found: make ===

If you see this error in Ubuntu, run <tt>sudo apt-get install build-essential</tt> and retry.

=== Current working directory is not a Cordova-based project. ===

If you see this error during <tt>npm setup</tt>, run <tt>mkdir www</tt> 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 'natives' prior to 1.1.6. I fixed it using <tt>npm install natives@1.1.6</tt>.

== See also ==

http://ionicframework.com/docs/cli/

Moodle App Plugins Development Guide

2019-02-04T16:19:39Z

TimHunt: /* Moodle version requirements */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supportedin 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.

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

=====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].
* 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]]

Moodle App Plugins Development Guide

2019-02-04T16:19:08Z

TimHunt: /* Step 5. Plugin webservices, if included */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supportedin 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 (to be released in May) 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.

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

=====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].
* 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]]