<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
	<id>https://docs.moodle.org/dev/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Timhunt</id>
	<title>MoodleDocs - User contributions [en]</title>
	<link rel="self" type="application/atom+xml" href="https://docs.moodle.org/dev/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Timhunt"/>
	<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/Special:Contributions/Timhunt"/>
	<updated>2026-11-21T07:07:27Z</updated>
	<subtitle>User contributions</subtitle>
	<generator>MediaWiki 1.43.5</generator>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=57205</id>
		<title>Integration Review</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=57205"/>
		<updated>2020-04-06T10:06:34Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* During continuous integration/Freeze/QA period */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;==Purpose==&lt;br /&gt;
&lt;br /&gt;
The purpose of the integration review is to:&lt;br /&gt;
* Ensure consistent quality across the codebase&lt;br /&gt;
* Ensure that pedagogical aims of Moodle are at the forefront of any change&lt;br /&gt;
* Take into consideration the holistic view of moodle, looking at the impact beyond where the original developer was focused&lt;br /&gt;
* Provide guidance and feedback to developers, helping them learn and improve &lt;br /&gt;
* Consider &#039;&#039;&#039;other perspectives&#039;&#039;&#039; of other users perhaps not considered by original developers e.g.&lt;br /&gt;
** Teachers&lt;br /&gt;
** Students&lt;br /&gt;
** Administrators&lt;br /&gt;
**Third-party developers&lt;br /&gt;
&lt;br /&gt;
==Integration Review Process==&lt;br /&gt;
&lt;br /&gt;
# Run automated pre-checks against the continuous integration server. (In future this can be automated and also moved into a publicly accessible domain.)&lt;br /&gt;
# Final code review, much like the peer review, except that this is the final check. To include&lt;br /&gt;
## Takes place in-situ (integrated) to examine the impact to other integrated issues&lt;br /&gt;
## Checking against the coding guidelines - syntax/whitespace&lt;br /&gt;
## Moodleisms - using the built-in API functions where appropriate&lt;br /&gt;
## Cross-DB compatibility &lt;br /&gt;
## Security&lt;br /&gt;
# Check purpose - the patch needs to fix the issue reported.&lt;br /&gt;
# Verify target branches are appropriated. They must match 100% the rules defined for [[#Backporting|backporting issues]].&lt;br /&gt;
# Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:&lt;br /&gt;
## Well discussed with evidence of justification&lt;br /&gt;
## Documented and communicated to the community &lt;br /&gt;
# Verify that components are correct and check the right people have been involved (e.g. component maintainers)&lt;br /&gt;
# For fundamental changes, check that a thread has been started in an appropriate forum, and other Moodlers, given enough time to comment.&lt;br /&gt;
# Tests - must be written to guide tester to verify the fix is working.&lt;br /&gt;
## Unit test - very much preferred if applicable&lt;br /&gt;
## at end of Wednesday, ensure testing is going to complete as expected. else take other actions (speak to test manager)&lt;br /&gt;
# Performance - we have to look at maintaining optimum code here, as far as simple patches that can affect performance. (simple optimisations)&lt;br /&gt;
# Scalability - if master only - we&#039;re looking far future, stable branches may not be lucky to get such improvements.&lt;br /&gt;
# git authorship is correct vs committer + credits due are mentioned + email addresses&lt;br /&gt;
# Documentation / PHP Doc / readability&lt;br /&gt;
# [[Tracker issue labels]] which might need adding. Particularly:&lt;br /&gt;
## docs_required / dev_docs_required / release_notes: About which type of documentation is required for the issue.&lt;br /&gt;
## ui_change / api_change: About the implications of the change.&lt;br /&gt;
## unit_test_required / acceptance_test_required / qa_test_required: About the need to cover the issue with some test.&lt;br /&gt;
# [[Tracker issue versions]] review. Particularly:&lt;br /&gt;
## Fixed Version after integration - is the versions that the issue is patched for. (A rule here: [[Tracker issue versions#Some general and simple rules|&amp;quot;or stables or master&amp;quot;]]).&lt;br /&gt;
## Remove any &amp;quot;Must fix for X.Y&amp;quot; version once the issue is integrated.&lt;br /&gt;
# Assign the tester.&lt;br /&gt;
## Don&#039;t forget to update the weight in the testers sheet&lt;br /&gt;
&lt;br /&gt;
== Integration Principles ==&lt;br /&gt;
&lt;br /&gt;
Integration (non-technical but philosophical) principles (4-5 words determining if something has to be integrated/backported or no):&lt;br /&gt;
&lt;br /&gt;
# safety: if something does not look safe, stable, it won&#039;t land. Be conservative.&lt;br /&gt;
# security: all security issues, if not breaking principle (1) will be integrated/backported to all security-supported versions.&lt;br /&gt;
# community: Anything not useful for the community (or against it) won&#039;t be integrated/backported. We can measure the community as 10%HQ, 10%Partners, 10%Core developers, 20%Admins, 20%Teachers, 30%Students - not exact science, just one approximation, you know). Question yourself how the change will affect those groups and ensure positives are bigger always (only affected groups count). All community issues, if not breaking principles (1) and (2) will be integrated.&lt;br /&gt;
# typology:  bug fixes will be always integrated/backported to all the supported braches if none of the principles (1), (2) and (3) are violated. Also, partially-unsupported branches can receive some if they are important enough. Improvements and new features go, exclusively, to master only, that&#039;s the main reason for short release periods. We *must* not make exceptions to this.&lt;br /&gt;
# priority: issues will be &amp;quot;ordered down&amp;quot; by priority down (where priority is a [https://tracker.moodle.org/issues/?filter=14000 mix of various factors], dynamic). And will be integrated in that order. If something has to be delayed, better if it is low priority. Once again, nothing here can break any of the previous principles.&lt;br /&gt;
# tests: unit tests and acceptance tests will backported as much as possible without breaking (1) and (2). New features required to implement tests will be backported if the API is 100% backwards compatible. &lt;br /&gt;
If all the principles are fulfilled, the answer for &amp;quot;should I integrate this?&amp;quot; is, &amp;quot;yes, please!&amp;quot;&lt;br /&gt;
(apart from technical findings, of course, that can lead to the issue being not integrated/reopened at last, these principles are 100% philosophical)&lt;br /&gt;
&lt;br /&gt;
==Schedule==&lt;br /&gt;
===In normal periods ===&lt;br /&gt;
The integrators adhere to the following schedule: (links here should convert the times into your local timezone)&lt;br /&gt;
&lt;br /&gt;
* Monday [http://time.unitarium.com/utc/23 07:00 (UTC+8)] and [http://time.unitarium.com/utc/11 19:00 (UTC+8)]: Issues waiting for integration are brought into current integration automatically.&lt;br /&gt;
* Monday to Thursday until [http://time.unitarium.com/utc/4 12:00 (UTC+8)]: Integration and [[Testing of integrated issues#The testing process|Testing]] happen.&lt;br /&gt;
* Thursday after 12:00 (UTC+8): Integrators duties during this time are to monitor, facilitate and &#039;problem solve&#039; the testing process.&lt;br /&gt;
* Friday: Testing should be completed before (the sooner the better) 12:00 (UTC+8) at which time remaining testing failures will be reverted/rewritten and reopened. The release process follows.&lt;br /&gt;
* Friday after 12:00 (UTC+8):: Should be kept free from integration. Integration systems are maintained during this time.&lt;br /&gt;
&lt;br /&gt;
Note that under the strict schedule above, it is specially important &#039;&#039;&#039;to be as responsive as possible&#039;&#039;&#039;, both when the issue is being integrated and when [[Testing_of_integrated_issues#Expectation_from_tester|testing]]. Any significant delay by any of the actors involved will result in the issue being moved out from current integration.&lt;br /&gt;
&lt;br /&gt;
=== During continuous integration/Freeze/QA period ===&lt;br /&gt;
During the continuous integration period (last 6 weeks before release) the integration team are continuously focused on producing regular builds of master to facilitate QA and fast fixes to issues identified.&lt;br /&gt;
&lt;br /&gt;
* Throughout:&lt;br /&gt;
** Issues are picked on a one by one basis, prioritising [https://docs.moodle.org/dev/QA_testing#Resetting_tests QA blockers] and master regressions (MUST FIX) issues.&lt;br /&gt;
** After freeze (usually 5 weeks before release) any non bug fix issues are given the &#039;&#039;integration_held&#039;&#039; label and are explicitly not picked for integration. Still, anybody is able to add a reasoned &#039;&#039;unhold_requested&#039;&#039; label to those issues in order to get them unblocked by the development managers. Note this does not guarantee the issue to land before release, but just gives it a chance to be integrated like any other issue.&lt;br /&gt;
** Our goal is to achieve &#039;releaseability&#039; throughout, so we stop integrating to ensure a release happens&lt;br /&gt;
&lt;br /&gt;
So, basically, once under continuous integration, we do organize work as follows:&lt;br /&gt;
* Continuous officially begins. Everybody is on integration. Until end of on-sync period.&lt;br /&gt;
* Monday: Integration and [[Testing of integrated issues#Differences in test process during continuous integration periods|testing]] happens.&lt;br /&gt;
* Tuesday: Integration happens until [http://time.unitarium.com/utc/4 12:00 (UTC+8)], [[Testing of integrated issues#Differences in test process during continuous integration periods|afterwards we try to achieve 100% &#039;Test Passed&#039;]] and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
* Wednesday: [Assuming a master release has been rolled] Integration and testing continues&lt;br /&gt;
* Thursday: Integration and testing continues&lt;br /&gt;
* Friday: Integration happens until 12:00 (UTC+8), afterwards we try to achieve 100% &#039;Test Passed&#039; and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
&lt;br /&gt;
Note: along this period we always release as many stable weeklies, both supported (always) and security only (when there are changes), as master rolls (on-demand, beta, rc) happen (see MDLSITE-3470). Note that those tags are not simply tags but they come with some important implications, aiming to stability, safety and clarity. Integrators will try to remain loyal to them, be warned:&lt;br /&gt;
&lt;br /&gt;
* Once beta is released... new features or improvements &amp;quot;unrelated&amp;quot; with the release will be really harder to be accepted. A +4 from developer managers (normally +3 is enough) will be needed to proceed with the issue. Integrators vote will be, always, -1.&lt;br /&gt;
* Once rc are released... new features or improvements &amp;quot;unrelated&amp;quot; with the release are forbidden. No unhold voting, no managers. Simply forbidden.&lt;br /&gt;
* Last week before release, only &amp;quot;related&amp;quot; issues will be picked for integration. Everything else (bug fixes included) are kept out (given the &amp;quot;integration_held&amp;quot; label) if unrelated, at very least until after release. No distractions.&lt;br /&gt;
Definition: &amp;quot;related&amp;quot;: said to be a followup of required/planned to release OR a direct (and recent) regression caused by a bug fix OR a security issue.&lt;br /&gt;
&lt;br /&gt;
=== On-sync period ===&lt;br /&gt;
Immediately after a major release and for a short period (right now, 2 weeks, matching 1st HQ sprint duration), the integration team is under the named on-sync period.&lt;br /&gt;
&lt;br /&gt;
At all effects, it&#039;s a normal period (see above), and weeklies are produced for supported stable branches and also for master. But with one important rule/goal:&lt;br /&gt;
&lt;br /&gt;
* We must keep the latest stable branch and master 100% on-sync, specifically about versions and upgrade steps. Some well-known exceptions to this are: &#039;&#039;.travis.yml&#039;&#039;, &#039;&#039;backup.class.php&#039;&#039;, &#039;&#039;config.php&#039;&#039; (&#039;&#039;$release&#039;&#039;, &#039;&#039;$branch&#039;&#039;, &#039;&#039;$maturity&#039;&#039; and comments only, never &#039;&#039;$version&#039;&#039; !), &#039;&#039;install/lang/xx&#039;&#039; files (the new stable branch for install lang files is created 2w after the release).&lt;br /&gt;
&lt;br /&gt;
This simple, but important constraint, is there to facilitate the integration of impeding bugs, needing urgent resolution, and by keeping them the same, we guarantee that any stable or master fix will apply without problems to both branches. Of course, in order to achieve the rule, these must be also observed along the period:&lt;br /&gt;
&lt;br /&gt;
* We continuously perform diffs between the latest stable and master, controlling that we are on-sync. Any non-authorised difference is cleaned (rewritten). Whenever a latest stable branch is missing in the issue (it&#039;s optional over the period), we automatically cherry pick the changes straight from master.&lt;br /&gt;
* Both improvements and new features (and, in general, everything leading to divergence) are held until the on-sync period ends.&lt;br /&gt;
&lt;br /&gt;
Last, but not less important, a second goal for this on-sync period is:&lt;br /&gt;
&lt;br /&gt;
* The environmental requirements &#039;&#039;&#039;for next major version&#039;&#039;&#039; [[Release process#2_weeks_after|must be agreed and resolved so they can land to master]] early in the process, remaining defined and stable over the next, 6 months of, development cycle.&lt;br /&gt;
&lt;br /&gt;
As part of the standard [https://docs.moodle.org/dev/Release_process Moodle release process], at the beginning of the on-sync period, we &amp;quot;unhold&amp;quot; all bugs that were held during the last week before the release because they were unrelated to the release. At the end of the onsync period we &amp;quot;unhold&amp;quot; all new features that were submitted after the code freeze for the the release.&lt;br /&gt;
&lt;br /&gt;
== Backporting ==&lt;br /&gt;
&lt;br /&gt;
Whilst we&#039;d all like all Moodle users to be using our latest and greatest code, there is a balance to strike between improving our software and maintaining stability (both in terms of regressions, but also training and documentation materials). Large amounts of change on the stable branches make the lives difficult for institutions to manage upgrades between point releases.&lt;br /&gt;
&lt;br /&gt;
==== General policy ====&lt;br /&gt;
Our general policy is as follows:&lt;br /&gt;
&lt;br /&gt;
* Bug fixes will be backported to all (and only to) supported stable branches. &lt;br /&gt;
** When fixing a bug, please provide a fix for all supported stable branches. &lt;br /&gt;
** If a fix doesn&#039;t make sense to be backported to every branch, please make it clear in the issue.&lt;br /&gt;
* Improvements or new features will only land in master.&lt;br /&gt;
&lt;br /&gt;
==== Process for requesting a non bug-fix backport ====&lt;br /&gt;
Improvements or new features can be requested to be backported to the stable branches. We urge developers to consider this request carefully. In recent years, Moodle has moved to a short and predicatable time based release schedule and we use a very effective distributed source control system. Both of these process changes should ensure that a change not being backported to the stable branches is not as problematic as it may have used to be. &lt;br /&gt;
&lt;br /&gt;
Should you feel that a new feature or improvement needs backporting, please follow this process:&lt;br /&gt;
&lt;br /&gt;
# File a new issue.&lt;br /&gt;
# Set the issue title using our backport template guide.  (i.e. &amp;quot;Fix forum alignment (backport of MDL-99999)&amp;quot;) - see [https://docs.moodle.org/dev/Tracker_guide#Tracker_fields Tracker_guide]&lt;br /&gt;
# Link the original issue using link type &amp;quot;Will help resolve&amp;quot;.&lt;br /&gt;
# You should include clear rationale for the request to backport&lt;br /&gt;
&lt;br /&gt;
The integration team will process backport requests, with the following guidelines:&lt;br /&gt;
# The integration team will together consider each request individually considering the needs of the community (influenced by forum posts, moodle partners, nagging developers etc).&lt;br /&gt;
# Backports will happen not earlier than 3 weeks and not later than 2 months after the issue has landed in master.&lt;br /&gt;
# Rationale will be given for rejection&lt;br /&gt;
&lt;br /&gt;
If the backport request is approved, please follow the usual development process to submit the feature or improvement on earlier branches. Just to be clear, this means using the new bug number. So, even if the fix you are back-porting cherry-picks cleanly, you will need to amend the commit comment to use the new MDL-XXXXX number. It would be good practice to also add a line like &amp;quot;This is a backport of MDL-YYYYY.&amp;quot; in the amended commit comment. You can probably copy the testing instructions from the original issue. If so, make it clear you done this by saying something like &amp;quot;Copied from MDL-66327:&amp;quot;. Of course, if you can improve the instructions, feel free to edit. MDL-66614 and MDL-66327 are probably a reasonably good example fo what should be done.&lt;br /&gt;
&lt;br /&gt;
==== Polite note about bug classification ====&lt;br /&gt;
Many issues can be appropiately classified as borderline bugfix/improvements. We politely request that developers do not try and &#039;game the system&#039; by clasifying their improvements as bugs intentionally. If your fix is in a grey area, please state your case for it being a bug fix clearly. The integration team will use their discretion where necessary.&lt;br /&gt;
&lt;br /&gt;
==== Backport fixes to unsupported branches ====&lt;br /&gt;
* Given the [[#General policy|general policy]] above, only supported stable branches are candidates normally.&lt;br /&gt;
* Also security, privacy and dataloss issues are accepted to be fixed into security-only supported branches.&lt;br /&gt;
* Apart from the previous, issues required to keep the testing infrastructure working and passing (travis, behat, phpunit, random failures, new steps availability...) will also be accepted when possible into security-only branches.&lt;br /&gt;
* Finally, backport to unsupported branches only will happen when the issue is a &#039;&#039;&#039;direct regression caused by a bug fix&#039;&#039;&#039; introduced by the very latest releases. This applies to both security-only and out-of-support branches.&lt;br /&gt;
&lt;br /&gt;
A new weekly release will be performed including all the cases above, but  [[Process#Security issues|security issues that follow its own special process]] and are released bi-monthly.&lt;br /&gt;
&lt;br /&gt;
== Fixing issues identified during integration review/ testing ==&lt;br /&gt;
&lt;br /&gt;
When a branch has been merged by an integrator, it is important that you do not modify the existing history of your branch (e.g. by amending or squashing your commits) and instead add new commits on top. If you modify the history of your branch, it makes it extremely difficult for the integrator to merge your changes (and see the differences).&lt;br /&gt;
&lt;br /&gt;
As a general rule, this means that if your issue has entered the &#039;in integration review&#039; stage of the development process, please only add new commits on top of your existing commits. There are circumstances when your issue will be &#039;in integration review&#039; but not merged (and thus possible to squash changes) but if in any doubt, please add new commits and ask the integrator to squash your changes for you.&lt;br /&gt;
&lt;br /&gt;
== Commit squashing ==&lt;br /&gt;
&lt;br /&gt;
The Integration team will sometimes recommend squashing commits when things do not look natural (and may offer to do this for you), especially when there are &amp;quot;fix-commits&amp;quot; in the history happening before integration. But [https://moodle.org/local/chatlogs/index.php?conversationid=13987#c489485 our policy] is &amp;quot;if you want your history of commits to look like bad, it&#039;s your history&amp;quot;. You will not be forced to squash your changes. You should pay close attention to https://docs.moodle.org/dev/Coding_style#Git_commits and intend to  &amp;quot;Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
[[Category: Processes]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=57204</id>
		<title>Integration Review</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=57204"/>
		<updated>2020-04-06T10:04:00Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* In normal periods */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;==Purpose==&lt;br /&gt;
&lt;br /&gt;
The purpose of the integration review is to:&lt;br /&gt;
* Ensure consistent quality across the codebase&lt;br /&gt;
* Ensure that pedagogical aims of Moodle are at the forefront of any change&lt;br /&gt;
* Take into consideration the holistic view of moodle, looking at the impact beyond where the original developer was focused&lt;br /&gt;
* Provide guidance and feedback to developers, helping them learn and improve &lt;br /&gt;
* Consider &#039;&#039;&#039;other perspectives&#039;&#039;&#039; of other users perhaps not considered by original developers e.g.&lt;br /&gt;
** Teachers&lt;br /&gt;
** Students&lt;br /&gt;
** Administrators&lt;br /&gt;
**Third-party developers&lt;br /&gt;
&lt;br /&gt;
==Integration Review Process==&lt;br /&gt;
&lt;br /&gt;
# Run automated pre-checks against the continuous integration server. (In future this can be automated and also moved into a publicly accessible domain.)&lt;br /&gt;
# Final code review, much like the peer review, except that this is the final check. To include&lt;br /&gt;
## Takes place in-situ (integrated) to examine the impact to other integrated issues&lt;br /&gt;
## Checking against the coding guidelines - syntax/whitespace&lt;br /&gt;
## Moodleisms - using the built-in API functions where appropriate&lt;br /&gt;
## Cross-DB compatibility &lt;br /&gt;
## Security&lt;br /&gt;
# Check purpose - the patch needs to fix the issue reported.&lt;br /&gt;
# Verify target branches are appropriated. They must match 100% the rules defined for [[#Backporting|backporting issues]].&lt;br /&gt;
# Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:&lt;br /&gt;
## Well discussed with evidence of justification&lt;br /&gt;
## Documented and communicated to the community &lt;br /&gt;
# Verify that components are correct and check the right people have been involved (e.g. component maintainers)&lt;br /&gt;
# For fundamental changes, check that a thread has been started in an appropriate forum, and other Moodlers, given enough time to comment.&lt;br /&gt;
# Tests - must be written to guide tester to verify the fix is working.&lt;br /&gt;
## Unit test - very much preferred if applicable&lt;br /&gt;
## at end of Wednesday, ensure testing is going to complete as expected. else take other actions (speak to test manager)&lt;br /&gt;
# Performance - we have to look at maintaining optimum code here, as far as simple patches that can affect performance. (simple optimisations)&lt;br /&gt;
# Scalability - if master only - we&#039;re looking far future, stable branches may not be lucky to get such improvements.&lt;br /&gt;
# git authorship is correct vs committer + credits due are mentioned + email addresses&lt;br /&gt;
# Documentation / PHP Doc / readability&lt;br /&gt;
# [[Tracker issue labels]] which might need adding. Particularly:&lt;br /&gt;
## docs_required / dev_docs_required / release_notes: About which type of documentation is required for the issue.&lt;br /&gt;
## ui_change / api_change: About the implications of the change.&lt;br /&gt;
## unit_test_required / acceptance_test_required / qa_test_required: About the need to cover the issue with some test.&lt;br /&gt;
# [[Tracker issue versions]] review. Particularly:&lt;br /&gt;
## Fixed Version after integration - is the versions that the issue is patched for. (A rule here: [[Tracker issue versions#Some general and simple rules|&amp;quot;or stables or master&amp;quot;]]).&lt;br /&gt;
## Remove any &amp;quot;Must fix for X.Y&amp;quot; version once the issue is integrated.&lt;br /&gt;
# Assign the tester.&lt;br /&gt;
## Don&#039;t forget to update the weight in the testers sheet&lt;br /&gt;
&lt;br /&gt;
== Integration Principles ==&lt;br /&gt;
&lt;br /&gt;
Integration (non-technical but philosophical) principles (4-5 words determining if something has to be integrated/backported or no):&lt;br /&gt;
&lt;br /&gt;
# safety: if something does not look safe, stable, it won&#039;t land. Be conservative.&lt;br /&gt;
# security: all security issues, if not breaking principle (1) will be integrated/backported to all security-supported versions.&lt;br /&gt;
# community: Anything not useful for the community (or against it) won&#039;t be integrated/backported. We can measure the community as 10%HQ, 10%Partners, 10%Core developers, 20%Admins, 20%Teachers, 30%Students - not exact science, just one approximation, you know). Question yourself how the change will affect those groups and ensure positives are bigger always (only affected groups count). All community issues, if not breaking principles (1) and (2) will be integrated.&lt;br /&gt;
# typology:  bug fixes will be always integrated/backported to all the supported braches if none of the principles (1), (2) and (3) are violated. Also, partially-unsupported branches can receive some if they are important enough. Improvements and new features go, exclusively, to master only, that&#039;s the main reason for short release periods. We *must* not make exceptions to this.&lt;br /&gt;
# priority: issues will be &amp;quot;ordered down&amp;quot; by priority down (where priority is a [https://tracker.moodle.org/issues/?filter=14000 mix of various factors], dynamic). And will be integrated in that order. If something has to be delayed, better if it is low priority. Once again, nothing here can break any of the previous principles.&lt;br /&gt;
# tests: unit tests and acceptance tests will backported as much as possible without breaking (1) and (2). New features required to implement tests will be backported if the API is 100% backwards compatible. &lt;br /&gt;
If all the principles are fulfilled, the answer for &amp;quot;should I integrate this?&amp;quot; is, &amp;quot;yes, please!&amp;quot;&lt;br /&gt;
(apart from technical findings, of course, that can lead to the issue being not integrated/reopened at last, these principles are 100% philosophical)&lt;br /&gt;
&lt;br /&gt;
==Schedule==&lt;br /&gt;
===In normal periods ===&lt;br /&gt;
The integrators adhere to the following schedule: (links here should convert the times into your local timezone)&lt;br /&gt;
&lt;br /&gt;
* Monday [http://time.unitarium.com/utc/23 07:00 (UTC+8)] and [http://time.unitarium.com/utc/11 19:00 (UTC+8)]: Issues waiting for integration are brought into current integration automatically.&lt;br /&gt;
* Monday to Thursday until [http://time.unitarium.com/utc/4 12:00 (UTC+8)]: Integration and [[Testing of integrated issues#The testing process|Testing]] happen.&lt;br /&gt;
* Thursday after 12:00 (UTC+8): Integrators duties during this time are to monitor, facilitate and &#039;problem solve&#039; the testing process.&lt;br /&gt;
* Friday: Testing should be completed before (the sooner the better) 12:00 (UTC+8) at which time remaining testing failures will be reverted/rewritten and reopened. The release process follows.&lt;br /&gt;
* Friday after 12:00 (UTC+8):: Should be kept free from integration. Integration systems are maintained during this time.&lt;br /&gt;
&lt;br /&gt;
Note that under the strict schedule above, it is specially important &#039;&#039;&#039;to be as responsive as possible&#039;&#039;&#039;, both when the issue is being integrated and when [[Testing_of_integrated_issues#Expectation_from_tester|testing]]. Any significant delay by any of the actors involved will result in the issue being moved out from current integration.&lt;br /&gt;
&lt;br /&gt;
=== During continuous integration/Freeze/QA period ===&lt;br /&gt;
During the continuous integration period (last 6 weeks before release) the integration team are continuously focused on producing regular builds of master to facilitate QA and fast fixes to issues identified.&lt;br /&gt;
&lt;br /&gt;
* Throughout:&lt;br /&gt;
** Issues are picked on a one by one basis, prioritising [https://docs.moodle.org/dev/QA_testing#Resetting_tests QA blockers] and master regressions (MUST FIX) issues.&lt;br /&gt;
** After freeze (usually 5 weeks before release) any non bug fix issues are given the &#039;&#039;integration_held&#039;&#039; label and are explicitly not picked for integration. Still, anybody is able to add a reasoned &#039;&#039;unhold_requested&#039;&#039; label to those issues in order to get them unblocked by the development managers. Note this does not guarantee the issue to land before release, but just gives it a chance to be integrated like any other issue.&lt;br /&gt;
** Our goal is to achieve &#039;releaseability&#039; throughout, so we stop integrating to ensure a release happens&lt;br /&gt;
&lt;br /&gt;
So, basically, once under continuous integration, we do organize work as follows:&lt;br /&gt;
* Continuous officially begins. Everybody is on integration. Until end of on-sync period.&lt;br /&gt;
* Monday: Integration and [[Testing of integrated issues#Differences in test process during continuous integration periods|testing]] happens.&lt;br /&gt;
* Tuesday: Integration happens until 12:00 (UTC+8), [[Testing of integrated issues#Differences in test process during continuous integration periods|afterwards we try to achieve 100% &#039;Test Passed&#039;]] and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
* Wednesday: [Assuming a master release has been rolled] Integration and testing continues&lt;br /&gt;
* Thursday: Integration and testing continues&lt;br /&gt;
* Friday: Integration happens until 12:00 (UTC+8), afterwards we try to achieve 100% &#039;Test Passed&#039; and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
&lt;br /&gt;
Note: along this period we always release as many stable weeklies, both supported (always) and security only (when there are changes), as master rolls (on-demand, beta, rc) happen (see MDLSITE-3470). Note that those tags are not simply tags but they come with some important implications, aiming to stability, safety and clarity. Integrators will try to remain loyal to them, be warned:&lt;br /&gt;
&lt;br /&gt;
* Once beta is released... new features or improvements &amp;quot;unrelated&amp;quot; with the release will be really harder to be accepted. A +4 from developer managers (normally +3 is enough) will be needed to proceed with the issue. Integrators vote will be, always, -1.&lt;br /&gt;
* Once rc are released... new features or improvements &amp;quot;unrelated&amp;quot; with the release are forbidden. No unhold voting, no managers. Simply forbidden.&lt;br /&gt;
* Last week before release, only &amp;quot;related&amp;quot; issues will be picked for integration. Everything else (bug fixes included) are kept out (given the &amp;quot;integration_held&amp;quot; label) if unrelated, at very least until after release. No distractions.&lt;br /&gt;
Definition: &amp;quot;related&amp;quot;: said to be a followup of required/planned to release OR a direct (and recent) regression caused by a bug fix OR a security issue.&lt;br /&gt;
&lt;br /&gt;
=== On-sync period ===&lt;br /&gt;
Immediately after a major release and for a short period (right now, 2 weeks, matching 1st HQ sprint duration), the integration team is under the named on-sync period.&lt;br /&gt;
&lt;br /&gt;
At all effects, it&#039;s a normal period (see above), and weeklies are produced for supported stable branches and also for master. But with one important rule/goal:&lt;br /&gt;
&lt;br /&gt;
* We must keep the latest stable branch and master 100% on-sync, specifically about versions and upgrade steps. Some well-known exceptions to this are: &#039;&#039;.travis.yml&#039;&#039;, &#039;&#039;backup.class.php&#039;&#039;, &#039;&#039;config.php&#039;&#039; (&#039;&#039;$release&#039;&#039;, &#039;&#039;$branch&#039;&#039;, &#039;&#039;$maturity&#039;&#039; and comments only, never &#039;&#039;$version&#039;&#039; !), &#039;&#039;install/lang/xx&#039;&#039; files (the new stable branch for install lang files is created 2w after the release).&lt;br /&gt;
&lt;br /&gt;
This simple, but important constraint, is there to facilitate the integration of impeding bugs, needing urgent resolution, and by keeping them the same, we guarantee that any stable or master fix will apply without problems to both branches. Of course, in order to achieve the rule, these must be also observed along the period:&lt;br /&gt;
&lt;br /&gt;
* We continuously perform diffs between the latest stable and master, controlling that we are on-sync. Any non-authorised difference is cleaned (rewritten). Whenever a latest stable branch is missing in the issue (it&#039;s optional over the period), we automatically cherry pick the changes straight from master.&lt;br /&gt;
* Both improvements and new features (and, in general, everything leading to divergence) are held until the on-sync period ends.&lt;br /&gt;
&lt;br /&gt;
Last, but not less important, a second goal for this on-sync period is:&lt;br /&gt;
&lt;br /&gt;
* The environmental requirements &#039;&#039;&#039;for next major version&#039;&#039;&#039; [[Release process#2_weeks_after|must be agreed and resolved so they can land to master]] early in the process, remaining defined and stable over the next, 6 months of, development cycle.&lt;br /&gt;
&lt;br /&gt;
As part of the standard [https://docs.moodle.org/dev/Release_process Moodle release process], at the beginning of the on-sync period, we &amp;quot;unhold&amp;quot; all bugs that were held during the last week before the release because they were unrelated to the release. At the end of the onsync period we &amp;quot;unhold&amp;quot; all new features that were submitted after the code freeze for the the release.&lt;br /&gt;
&lt;br /&gt;
== Backporting ==&lt;br /&gt;
&lt;br /&gt;
Whilst we&#039;d all like all Moodle users to be using our latest and greatest code, there is a balance to strike between improving our software and maintaining stability (both in terms of regressions, but also training and documentation materials). Large amounts of change on the stable branches make the lives difficult for institutions to manage upgrades between point releases.&lt;br /&gt;
&lt;br /&gt;
==== General policy ====&lt;br /&gt;
Our general policy is as follows:&lt;br /&gt;
&lt;br /&gt;
* Bug fixes will be backported to all (and only to) supported stable branches. &lt;br /&gt;
** When fixing a bug, please provide a fix for all supported stable branches. &lt;br /&gt;
** If a fix doesn&#039;t make sense to be backported to every branch, please make it clear in the issue.&lt;br /&gt;
* Improvements or new features will only land in master.&lt;br /&gt;
&lt;br /&gt;
==== Process for requesting a non bug-fix backport ====&lt;br /&gt;
Improvements or new features can be requested to be backported to the stable branches. We urge developers to consider this request carefully. In recent years, Moodle has moved to a short and predicatable time based release schedule and we use a very effective distributed source control system. Both of these process changes should ensure that a change not being backported to the stable branches is not as problematic as it may have used to be. &lt;br /&gt;
&lt;br /&gt;
Should you feel that a new feature or improvement needs backporting, please follow this process:&lt;br /&gt;
&lt;br /&gt;
# File a new issue.&lt;br /&gt;
# Set the issue title using our backport template guide.  (i.e. &amp;quot;Fix forum alignment (backport of MDL-99999)&amp;quot;) - see [https://docs.moodle.org/dev/Tracker_guide#Tracker_fields Tracker_guide]&lt;br /&gt;
# Link the original issue using link type &amp;quot;Will help resolve&amp;quot;.&lt;br /&gt;
# You should include clear rationale for the request to backport&lt;br /&gt;
&lt;br /&gt;
The integration team will process backport requests, with the following guidelines:&lt;br /&gt;
# The integration team will together consider each request individually considering the needs of the community (influenced by forum posts, moodle partners, nagging developers etc).&lt;br /&gt;
# Backports will happen not earlier than 3 weeks and not later than 2 months after the issue has landed in master.&lt;br /&gt;
# Rationale will be given for rejection&lt;br /&gt;
&lt;br /&gt;
If the backport request is approved, please follow the usual development process to submit the feature or improvement on earlier branches. Just to be clear, this means using the new bug number. So, even if the fix you are back-porting cherry-picks cleanly, you will need to amend the commit comment to use the new MDL-XXXXX number. It would be good practice to also add a line like &amp;quot;This is a backport of MDL-YYYYY.&amp;quot; in the amended commit comment. You can probably copy the testing instructions from the original issue. If so, make it clear you done this by saying something like &amp;quot;Copied from MDL-66327:&amp;quot;. Of course, if you can improve the instructions, feel free to edit. MDL-66614 and MDL-66327 are probably a reasonably good example fo what should be done.&lt;br /&gt;
&lt;br /&gt;
==== Polite note about bug classification ====&lt;br /&gt;
Many issues can be appropiately classified as borderline bugfix/improvements. We politely request that developers do not try and &#039;game the system&#039; by clasifying their improvements as bugs intentionally. If your fix is in a grey area, please state your case for it being a bug fix clearly. The integration team will use their discretion where necessary.&lt;br /&gt;
&lt;br /&gt;
==== Backport fixes to unsupported branches ====&lt;br /&gt;
* Given the [[#General policy|general policy]] above, only supported stable branches are candidates normally.&lt;br /&gt;
* Also security, privacy and dataloss issues are accepted to be fixed into security-only supported branches.&lt;br /&gt;
* Apart from the previous, issues required to keep the testing infrastructure working and passing (travis, behat, phpunit, random failures, new steps availability...) will also be accepted when possible into security-only branches.&lt;br /&gt;
* Finally, backport to unsupported branches only will happen when the issue is a &#039;&#039;&#039;direct regression caused by a bug fix&#039;&#039;&#039; introduced by the very latest releases. This applies to both security-only and out-of-support branches.&lt;br /&gt;
&lt;br /&gt;
A new weekly release will be performed including all the cases above, but  [[Process#Security issues|security issues that follow its own special process]] and are released bi-monthly.&lt;br /&gt;
&lt;br /&gt;
== Fixing issues identified during integration review/ testing ==&lt;br /&gt;
&lt;br /&gt;
When a branch has been merged by an integrator, it is important that you do not modify the existing history of your branch (e.g. by amending or squashing your commits) and instead add new commits on top. If you modify the history of your branch, it makes it extremely difficult for the integrator to merge your changes (and see the differences).&lt;br /&gt;
&lt;br /&gt;
As a general rule, this means that if your issue has entered the &#039;in integration review&#039; stage of the development process, please only add new commits on top of your existing commits. There are circumstances when your issue will be &#039;in integration review&#039; but not merged (and thus possible to squash changes) but if in any doubt, please add new commits and ask the integrator to squash your changes for you.&lt;br /&gt;
&lt;br /&gt;
== Commit squashing ==&lt;br /&gt;
&lt;br /&gt;
The Integration team will sometimes recommend squashing commits when things do not look natural (and may offer to do this for you), especially when there are &amp;quot;fix-commits&amp;quot; in the history happening before integration. But [https://moodle.org/local/chatlogs/index.php?conversationid=13987#c489485 our policy] is &amp;quot;if you want your history of commits to look like bad, it&#039;s your history&amp;quot;. You will not be forced to squash your changes. You should pay close attention to https://docs.moodle.org/dev/Coding_style#Git_commits and intend to  &amp;quot;Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
[[Category: Processes]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=57203</id>
		<title>Integration Review</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=57203"/>
		<updated>2020-04-06T10:01:24Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* In normal periods */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;==Purpose==&lt;br /&gt;
&lt;br /&gt;
The purpose of the integration review is to:&lt;br /&gt;
* Ensure consistent quality across the codebase&lt;br /&gt;
* Ensure that pedagogical aims of Moodle are at the forefront of any change&lt;br /&gt;
* Take into consideration the holistic view of moodle, looking at the impact beyond where the original developer was focused&lt;br /&gt;
* Provide guidance and feedback to developers, helping them learn and improve &lt;br /&gt;
* Consider &#039;&#039;&#039;other perspectives&#039;&#039;&#039; of other users perhaps not considered by original developers e.g.&lt;br /&gt;
** Teachers&lt;br /&gt;
** Students&lt;br /&gt;
** Administrators&lt;br /&gt;
**Third-party developers&lt;br /&gt;
&lt;br /&gt;
==Integration Review Process==&lt;br /&gt;
&lt;br /&gt;
# Run automated pre-checks against the continuous integration server. (In future this can be automated and also moved into a publicly accessible domain.)&lt;br /&gt;
# Final code review, much like the peer review, except that this is the final check. To include&lt;br /&gt;
## Takes place in-situ (integrated) to examine the impact to other integrated issues&lt;br /&gt;
## Checking against the coding guidelines - syntax/whitespace&lt;br /&gt;
## Moodleisms - using the built-in API functions where appropriate&lt;br /&gt;
## Cross-DB compatibility &lt;br /&gt;
## Security&lt;br /&gt;
# Check purpose - the patch needs to fix the issue reported.&lt;br /&gt;
# Verify target branches are appropriated. They must match 100% the rules defined for [[#Backporting|backporting issues]].&lt;br /&gt;
# Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:&lt;br /&gt;
## Well discussed with evidence of justification&lt;br /&gt;
## Documented and communicated to the community &lt;br /&gt;
# Verify that components are correct and check the right people have been involved (e.g. component maintainers)&lt;br /&gt;
# For fundamental changes, check that a thread has been started in an appropriate forum, and other Moodlers, given enough time to comment.&lt;br /&gt;
# Tests - must be written to guide tester to verify the fix is working.&lt;br /&gt;
## Unit test - very much preferred if applicable&lt;br /&gt;
## at end of Wednesday, ensure testing is going to complete as expected. else take other actions (speak to test manager)&lt;br /&gt;
# Performance - we have to look at maintaining optimum code here, as far as simple patches that can affect performance. (simple optimisations)&lt;br /&gt;
# Scalability - if master only - we&#039;re looking far future, stable branches may not be lucky to get such improvements.&lt;br /&gt;
# git authorship is correct vs committer + credits due are mentioned + email addresses&lt;br /&gt;
# Documentation / PHP Doc / readability&lt;br /&gt;
# [[Tracker issue labels]] which might need adding. Particularly:&lt;br /&gt;
## docs_required / dev_docs_required / release_notes: About which type of documentation is required for the issue.&lt;br /&gt;
## ui_change / api_change: About the implications of the change.&lt;br /&gt;
## unit_test_required / acceptance_test_required / qa_test_required: About the need to cover the issue with some test.&lt;br /&gt;
# [[Tracker issue versions]] review. Particularly:&lt;br /&gt;
## Fixed Version after integration - is the versions that the issue is patched for. (A rule here: [[Tracker issue versions#Some general and simple rules|&amp;quot;or stables or master&amp;quot;]]).&lt;br /&gt;
## Remove any &amp;quot;Must fix for X.Y&amp;quot; version once the issue is integrated.&lt;br /&gt;
# Assign the tester.&lt;br /&gt;
## Don&#039;t forget to update the weight in the testers sheet&lt;br /&gt;
&lt;br /&gt;
== Integration Principles ==&lt;br /&gt;
&lt;br /&gt;
Integration (non-technical but philosophical) principles (4-5 words determining if something has to be integrated/backported or no):&lt;br /&gt;
&lt;br /&gt;
# safety: if something does not look safe, stable, it won&#039;t land. Be conservative.&lt;br /&gt;
# security: all security issues, if not breaking principle (1) will be integrated/backported to all security-supported versions.&lt;br /&gt;
# community: Anything not useful for the community (or against it) won&#039;t be integrated/backported. We can measure the community as 10%HQ, 10%Partners, 10%Core developers, 20%Admins, 20%Teachers, 30%Students - not exact science, just one approximation, you know). Question yourself how the change will affect those groups and ensure positives are bigger always (only affected groups count). All community issues, if not breaking principles (1) and (2) will be integrated.&lt;br /&gt;
# typology:  bug fixes will be always integrated/backported to all the supported braches if none of the principles (1), (2) and (3) are violated. Also, partially-unsupported branches can receive some if they are important enough. Improvements and new features go, exclusively, to master only, that&#039;s the main reason for short release periods. We *must* not make exceptions to this.&lt;br /&gt;
# priority: issues will be &amp;quot;ordered down&amp;quot; by priority down (where priority is a [https://tracker.moodle.org/issues/?filter=14000 mix of various factors], dynamic). And will be integrated in that order. If something has to be delayed, better if it is low priority. Once again, nothing here can break any of the previous principles.&lt;br /&gt;
# tests: unit tests and acceptance tests will backported as much as possible without breaking (1) and (2). New features required to implement tests will be backported if the API is 100% backwards compatible. &lt;br /&gt;
If all the principles are fulfilled, the answer for &amp;quot;should I integrate this?&amp;quot; is, &amp;quot;yes, please!&amp;quot;&lt;br /&gt;
(apart from technical findings, of course, that can lead to the issue being not integrated/reopened at last, these principles are 100% philosophical)&lt;br /&gt;
&lt;br /&gt;
==Schedule==&lt;br /&gt;
===In normal periods ===&lt;br /&gt;
The integrators adhere to the following schedule:&lt;br /&gt;
&lt;br /&gt;
* Monday [http://time.unitarium.com/utc/23 07:00 (UTC+8)] and [http://time.unitarium.com/utc/11 19:00 (UTC+8)]: Issues waiting for integration are brought into current integration automatically.&lt;br /&gt;
* Monday to Thursday until 12:00 (UTC+8): Integration and [[Testing of integrated issues#The testing process|Testing]] happen.&lt;br /&gt;
* Thursday after 12:00 (UTC+8): Integrators duties during this time are to monitor, facilitate and &#039;problem solve&#039; the testing process.&lt;br /&gt;
* Friday: Testing should be completed before (the sooner the better) 12:00 (UTC+8) at which time remaining testing failures will be reverted/rewritten and reopened. The release process follows.&lt;br /&gt;
* Friday after 12:00 (UTC+8):: Should be kept free from integration. Integration systems are maintained during this time.&lt;br /&gt;
&lt;br /&gt;
Note that under the strict schedule above, it is specially important &#039;&#039;&#039;to be as responsive as possible&#039;&#039;&#039;, both when the issue is being integrated and when [[Testing_of_integrated_issues#Expectation_from_tester|testing]]. Any significant delay by any of the actors involved will result in the issue being moved out from current integration.&lt;br /&gt;
&lt;br /&gt;
=== During continuous integration/Freeze/QA period ===&lt;br /&gt;
During the continuous integration period (last 6 weeks before release) the integration team are continuously focused on producing regular builds of master to facilitate QA and fast fixes to issues identified.&lt;br /&gt;
&lt;br /&gt;
* Throughout:&lt;br /&gt;
** Issues are picked on a one by one basis, prioritising [https://docs.moodle.org/dev/QA_testing#Resetting_tests QA blockers] and master regressions (MUST FIX) issues.&lt;br /&gt;
** After freeze (usually 5 weeks before release) any non bug fix issues are given the &#039;&#039;integration_held&#039;&#039; label and are explicitly not picked for integration. Still, anybody is able to add a reasoned &#039;&#039;unhold_requested&#039;&#039; label to those issues in order to get them unblocked by the development managers. Note this does not guarantee the issue to land before release, but just gives it a chance to be integrated like any other issue.&lt;br /&gt;
** Our goal is to achieve &#039;releaseability&#039; throughout, so we stop integrating to ensure a release happens&lt;br /&gt;
&lt;br /&gt;
So, basically, once under continuous integration, we do organize work as follows:&lt;br /&gt;
* Continuous officially begins. Everybody is on integration. Until end of on-sync period.&lt;br /&gt;
* Monday: Integration and [[Testing of integrated issues#Differences in test process during continuous integration periods|testing]] happens.&lt;br /&gt;
* Tuesday: Integration happens until 12:00 (UTC+8), [[Testing of integrated issues#Differences in test process during continuous integration periods|afterwards we try to achieve 100% &#039;Test Passed&#039;]] and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
* Wednesday: [Assuming a master release has been rolled] Integration and testing continues&lt;br /&gt;
* Thursday: Integration and testing continues&lt;br /&gt;
* Friday: Integration happens until 12:00 (UTC+8), afterwards we try to achieve 100% &#039;Test Passed&#039; and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
&lt;br /&gt;
Note: along this period we always release as many stable weeklies, both supported (always) and security only (when there are changes), as master rolls (on-demand, beta, rc) happen (see MDLSITE-3470). Note that those tags are not simply tags but they come with some important implications, aiming to stability, safety and clarity. Integrators will try to remain loyal to them, be warned:&lt;br /&gt;
&lt;br /&gt;
* Once beta is released... new features or improvements &amp;quot;unrelated&amp;quot; with the release will be really harder to be accepted. A +4 from developer managers (normally +3 is enough) will be needed to proceed with the issue. Integrators vote will be, always, -1.&lt;br /&gt;
* Once rc are released... new features or improvements &amp;quot;unrelated&amp;quot; with the release are forbidden. No unhold voting, no managers. Simply forbidden.&lt;br /&gt;
* Last week before release, only &amp;quot;related&amp;quot; issues will be picked for integration. Everything else (bug fixes included) are kept out (given the &amp;quot;integration_held&amp;quot; label) if unrelated, at very least until after release. No distractions.&lt;br /&gt;
Definition: &amp;quot;related&amp;quot;: said to be a followup of required/planned to release OR a direct (and recent) regression caused by a bug fix OR a security issue.&lt;br /&gt;
&lt;br /&gt;
=== On-sync period ===&lt;br /&gt;
Immediately after a major release and for a short period (right now, 2 weeks, matching 1st HQ sprint duration), the integration team is under the named on-sync period.&lt;br /&gt;
&lt;br /&gt;
At all effects, it&#039;s a normal period (see above), and weeklies are produced for supported stable branches and also for master. But with one important rule/goal:&lt;br /&gt;
&lt;br /&gt;
* We must keep the latest stable branch and master 100% on-sync, specifically about versions and upgrade steps. Some well-known exceptions to this are: &#039;&#039;.travis.yml&#039;&#039;, &#039;&#039;backup.class.php&#039;&#039;, &#039;&#039;config.php&#039;&#039; (&#039;&#039;$release&#039;&#039;, &#039;&#039;$branch&#039;&#039;, &#039;&#039;$maturity&#039;&#039; and comments only, never &#039;&#039;$version&#039;&#039; !), &#039;&#039;install/lang/xx&#039;&#039; files (the new stable branch for install lang files is created 2w after the release).&lt;br /&gt;
&lt;br /&gt;
This simple, but important constraint, is there to facilitate the integration of impeding bugs, needing urgent resolution, and by keeping them the same, we guarantee that any stable or master fix will apply without problems to both branches. Of course, in order to achieve the rule, these must be also observed along the period:&lt;br /&gt;
&lt;br /&gt;
* We continuously perform diffs between the latest stable and master, controlling that we are on-sync. Any non-authorised difference is cleaned (rewritten). Whenever a latest stable branch is missing in the issue (it&#039;s optional over the period), we automatically cherry pick the changes straight from master.&lt;br /&gt;
* Both improvements and new features (and, in general, everything leading to divergence) are held until the on-sync period ends.&lt;br /&gt;
&lt;br /&gt;
Last, but not less important, a second goal for this on-sync period is:&lt;br /&gt;
&lt;br /&gt;
* The environmental requirements &#039;&#039;&#039;for next major version&#039;&#039;&#039; [[Release process#2_weeks_after|must be agreed and resolved so they can land to master]] early in the process, remaining defined and stable over the next, 6 months of, development cycle.&lt;br /&gt;
&lt;br /&gt;
As part of the standard [https://docs.moodle.org/dev/Release_process Moodle release process], at the beginning of the on-sync period, we &amp;quot;unhold&amp;quot; all bugs that were held during the last week before the release because they were unrelated to the release. At the end of the onsync period we &amp;quot;unhold&amp;quot; all new features that were submitted after the code freeze for the the release.&lt;br /&gt;
&lt;br /&gt;
== Backporting ==&lt;br /&gt;
&lt;br /&gt;
Whilst we&#039;d all like all Moodle users to be using our latest and greatest code, there is a balance to strike between improving our software and maintaining stability (both in terms of regressions, but also training and documentation materials). Large amounts of change on the stable branches make the lives difficult for institutions to manage upgrades between point releases.&lt;br /&gt;
&lt;br /&gt;
==== General policy ====&lt;br /&gt;
Our general policy is as follows:&lt;br /&gt;
&lt;br /&gt;
* Bug fixes will be backported to all (and only to) supported stable branches. &lt;br /&gt;
** When fixing a bug, please provide a fix for all supported stable branches. &lt;br /&gt;
** If a fix doesn&#039;t make sense to be backported to every branch, please make it clear in the issue.&lt;br /&gt;
* Improvements or new features will only land in master.&lt;br /&gt;
&lt;br /&gt;
==== Process for requesting a non bug-fix backport ====&lt;br /&gt;
Improvements or new features can be requested to be backported to the stable branches. We urge developers to consider this request carefully. In recent years, Moodle has moved to a short and predicatable time based release schedule and we use a very effective distributed source control system. Both of these process changes should ensure that a change not being backported to the stable branches is not as problematic as it may have used to be. &lt;br /&gt;
&lt;br /&gt;
Should you feel that a new feature or improvement needs backporting, please follow this process:&lt;br /&gt;
&lt;br /&gt;
# File a new issue.&lt;br /&gt;
# Set the issue title using our backport template guide.  (i.e. &amp;quot;Fix forum alignment (backport of MDL-99999)&amp;quot;) - see [https://docs.moodle.org/dev/Tracker_guide#Tracker_fields Tracker_guide]&lt;br /&gt;
# Link the original issue using link type &amp;quot;Will help resolve&amp;quot;.&lt;br /&gt;
# You should include clear rationale for the request to backport&lt;br /&gt;
&lt;br /&gt;
The integration team will process backport requests, with the following guidelines:&lt;br /&gt;
# The integration team will together consider each request individually considering the needs of the community (influenced by forum posts, moodle partners, nagging developers etc).&lt;br /&gt;
# Backports will happen not earlier than 3 weeks and not later than 2 months after the issue has landed in master.&lt;br /&gt;
# Rationale will be given for rejection&lt;br /&gt;
&lt;br /&gt;
If the backport request is approved, please follow the usual development process to submit the feature or improvement on earlier branches. Just to be clear, this means using the new bug number. So, even if the fix you are back-porting cherry-picks cleanly, you will need to amend the commit comment to use the new MDL-XXXXX number. It would be good practice to also add a line like &amp;quot;This is a backport of MDL-YYYYY.&amp;quot; in the amended commit comment. You can probably copy the testing instructions from the original issue. If so, make it clear you done this by saying something like &amp;quot;Copied from MDL-66327:&amp;quot;. Of course, if you can improve the instructions, feel free to edit. MDL-66614 and MDL-66327 are probably a reasonably good example fo what should be done.&lt;br /&gt;
&lt;br /&gt;
==== Polite note about bug classification ====&lt;br /&gt;
Many issues can be appropiately classified as borderline bugfix/improvements. We politely request that developers do not try and &#039;game the system&#039; by clasifying their improvements as bugs intentionally. If your fix is in a grey area, please state your case for it being a bug fix clearly. The integration team will use their discretion where necessary.&lt;br /&gt;
&lt;br /&gt;
==== Backport fixes to unsupported branches ====&lt;br /&gt;
* Given the [[#General policy|general policy]] above, only supported stable branches are candidates normally.&lt;br /&gt;
* Also security, privacy and dataloss issues are accepted to be fixed into security-only supported branches.&lt;br /&gt;
* Apart from the previous, issues required to keep the testing infrastructure working and passing (travis, behat, phpunit, random failures, new steps availability...) will also be accepted when possible into security-only branches.&lt;br /&gt;
* Finally, backport to unsupported branches only will happen when the issue is a &#039;&#039;&#039;direct regression caused by a bug fix&#039;&#039;&#039; introduced by the very latest releases. This applies to both security-only and out-of-support branches.&lt;br /&gt;
&lt;br /&gt;
A new weekly release will be performed including all the cases above, but  [[Process#Security issues|security issues that follow its own special process]] and are released bi-monthly.&lt;br /&gt;
&lt;br /&gt;
== Fixing issues identified during integration review/ testing ==&lt;br /&gt;
&lt;br /&gt;
When a branch has been merged by an integrator, it is important that you do not modify the existing history of your branch (e.g. by amending or squashing your commits) and instead add new commits on top. If you modify the history of your branch, it makes it extremely difficult for the integrator to merge your changes (and see the differences).&lt;br /&gt;
&lt;br /&gt;
As a general rule, this means that if your issue has entered the &#039;in integration review&#039; stage of the development process, please only add new commits on top of your existing commits. There are circumstances when your issue will be &#039;in integration review&#039; but not merged (and thus possible to squash changes) but if in any doubt, please add new commits and ask the integrator to squash your changes for you.&lt;br /&gt;
&lt;br /&gt;
== Commit squashing ==&lt;br /&gt;
&lt;br /&gt;
The Integration team will sometimes recommend squashing commits when things do not look natural (and may offer to do this for you), especially when there are &amp;quot;fix-commits&amp;quot; in the history happening before integration. But [https://moodle.org/local/chatlogs/index.php?conversationid=13987#c489485 our policy] is &amp;quot;if you want your history of commits to look like bad, it&#039;s your history&amp;quot;. You will not be forced to squash your changes. You should pay close attention to https://docs.moodle.org/dev/Coding_style#Git_commits and intend to  &amp;quot;Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
[[Category: Processes]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Renderer&amp;diff=57098</id>
		<title>Renderer</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Renderer&amp;diff=57098"/>
		<updated>2020-03-24T13:57:39Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;&#039;&#039;&#039;Note:&#039;&#039;&#039; More specific information can be found at [[Output renderers]] and [[Overriding a renderer]]&lt;br /&gt;
&lt;br /&gt;
A renderer works with Themes to display all of the output for any component of Moodle. This concept was introduced in Moodle 2.0 with the addition of $OUTPUT class and associated /lib php files. Moodle core, and each component, should have a renderers. You can also create a renderer for a special purpose, for example mod_quiz\output\edit_renderer. The point of renderers is to allow themes to have complete control over the HTML that is generated, usign the technique of [[Overriding a renderer]].&lt;br /&gt;
&lt;br /&gt;
Renderers should contains no logic other than what is required to generate the display, and should be compartmentalised into functional chunks. Each chunk should be responsible for producing a widget or control used within the component. This output will vary depending on the component.  For example the forum will have a method for displaying a forum post, displaying a thread (which most likely calls the forum post method), and displaying a search form.&lt;br /&gt;
&lt;br /&gt;
These days, acutally generating the HTML should be done with a template. The job of the render is then just to pass the data to the template in the expected format. Older renderes do the HTML generation in PHP code.&lt;br /&gt;
&lt;br /&gt;
Note, inside a renderer you should never refer to the globals $OUTPUT or $PAGE. You should use $this-&amp;gt;output and $this-&amp;gt;page. Plugin renderers should use methods from the core renderer whenever appropriate to keep the UI consistent. For example the forum renderer should use $this-&amp;gt;output-&amp;gt;heading() if it wants a heading (thought templates are changing this a bit). &lt;br /&gt;
&lt;br /&gt;
==Example of calling a renderer==&lt;br /&gt;
&lt;br /&gt;
When you actually want to do some output, you need to get an instance of your class (or whatever subclass the theme wants to substitute). For example:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
global $PAGE; // If necessary.&lt;br /&gt;
$wsoutput = $PAGE-&amp;gt;get_renderer(&#039;mod_workshop&#039;);&lt;br /&gt;
echo $wsoutput-&amp;gt;manual_allocation_interface($workshop, $allocationdata);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The mod_workshop_renderer object will have access to a moodle_core_renderer available as $this-&amp;gt;output. You should use this instead of global $OUTPUT, and you should use it. That is, boxes in the workshop should look like boxes elsewhere, so boxes in the workshop should be output with $this-&amp;gt;output-&amp;gt;box().&lt;br /&gt;
&lt;br /&gt;
==See also==&lt;br /&gt;
&lt;br /&gt;
* [[Themes 2.0 overriding a renderer]]&lt;br /&gt;
* [[Themes 2.0]]&lt;br /&gt;
* [[Themes 2.0 creating your first theme]]&lt;br /&gt;
* [[Output API]] &lt;br /&gt;
* [[Output functions]]&lt;br /&gt;
* [[Output renderers]]&lt;br /&gt;
* [[Overriding a renderer]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Acceptance_testing_for_the_Moodle_App&amp;diff=57089</id>
		<title>Acceptance testing for the Moodle App</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Acceptance_testing_for_the_Moodle_App&amp;diff=57089"/>
		<updated>2020-03-19T12:12:09Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;From Moodle 3.7 it is possible to write Behat tests for mobile app features.&lt;br /&gt;
&lt;br /&gt;
== Summary ==&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
A key point is that these tests for some parts of the mobile app are &#039;&#039;&#039;included within the Moodle codebase&#039;&#039;&#039;, not within the app codebase, because they are run using the Moodle Behat infrastructure. Therefore, you will need a Moodle development set-up as descrived in [[Setting up development environment]] for Moodle. 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.&lt;br /&gt;
&lt;br /&gt;
The main advantages of this approach are:&lt;br /&gt;
&lt;br /&gt;
* 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.&lt;br /&gt;
* Where institutions run tests automatically, it should be relatively easy to include some app tests within the existing approach.&lt;br /&gt;
* This system does not require any mobile device hardware and should work on all common platforms.&lt;br /&gt;
&lt;br /&gt;
This system has been tested on Windows 7 and Ubuntu 18.04 LTS.&lt;br /&gt;
&lt;br /&gt;
== Running Behat tests for the mobile app ==&lt;br /&gt;
&lt;br /&gt;
=== Set up a Moodle (web site) development environemnt ===&lt;br /&gt;
&lt;br /&gt;
If you don&#039;t already have one, you will need to get a Moodle site running on your localhost. This is described in  [[Setting up development environment]].&lt;br /&gt;
&lt;br /&gt;
=== Set up a mobile app development environment ===&lt;br /&gt;
&lt;br /&gt;
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. &lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
==== Setting up the environment yourself ====&lt;br /&gt;
&lt;br /&gt;
Follow the first part of the instructions on this page:&lt;br /&gt;
&lt;br /&gt;
* [[Setting up your development environment for Moodle Mobile 2]]&lt;br /&gt;
&lt;br /&gt;
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&#039;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).&lt;br /&gt;
&lt;br /&gt;
* 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.&lt;br /&gt;
&lt;br /&gt;
==== Setting up the environment using Docker ====&lt;br /&gt;
&lt;br /&gt;
(For this to work, you must have a Docker installation and know roughly how to use it.) &lt;br /&gt;
&lt;br /&gt;
You can run the app using a Docker image provided by Moodle HQ, with commands like these:&lt;br /&gt;
&lt;br /&gt;
* Specific version 3.6.0&lt;br /&gt;
&lt;br /&gt;
    docker run --rm -p 8100:8100 moodlehq/moodlemobile2:3.6.0&lt;br /&gt;
&lt;br /&gt;
* Latest stable version:&lt;br /&gt;
&lt;br /&gt;
    docker run --rm -p 8100:8100 moodlehq/moodlemobile2:latest&lt;br /&gt;
&lt;br /&gt;
* Nightly build of the next release&lt;br /&gt;
&lt;br /&gt;
    docker run --rm -p 8100:8100 moodlehq/moodlemobile2:next&lt;br /&gt;
&lt;br /&gt;
Nightly build images are created via Jenkins every time something new is integrated into the &amp;quot;integration&amp;quot; branch of the [http://github.com/moodlehq/moodlemobile2/ moodlemobile2 GitHub repository].&lt;br /&gt;
&lt;br /&gt;
Specific and latest stable images are created via Docker integration with GitHub every time a new version of the Moodle app is tagged.&lt;br /&gt;
&lt;br /&gt;
=== Add the mobile app Behat configuration ===&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
Broadly speaking the options are:&lt;br /&gt;
# Manage the Ionic app yourself&lt;br /&gt;
# Have Behat control the lifecycle (start/stop) of the ionic app&lt;br /&gt;
&lt;br /&gt;
The recommended option is to launch the App yourself using Docker.&lt;br /&gt;
&lt;br /&gt;
==== Manually launch the app environment yourself ====&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
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&#039;t running, tests which use the app will fail.&lt;br /&gt;
&lt;br /&gt;
To use this method then you need to add the following line to config.php:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$CFG-&amp;gt;behat_ionic_wwwroot = &#039;http://localhost:8100&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
There are two ways to run the app yourself:&lt;br /&gt;
# Using Docker&lt;br /&gt;
# Launching ionic yourself&lt;br /&gt;
&lt;br /&gt;
===== Using Docker (Recommended) =====&lt;br /&gt;
&lt;br /&gt;
If you are using the Docker image, you just need to start the Docker container:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
docker run -p 8100:8100 moodlehq/moodlemobile2&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===== Using a local installation =====&lt;br /&gt;
&lt;br /&gt;
If you have installed the development environment locally, you can launch it using &amp;lt;tt&amp;gt;ionic serve -b&amp;lt;/tt&amp;gt;. After launching it you will see output like:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
[OK] Development server running!&lt;br /&gt;
     Local: http://localhost:8100&lt;br /&gt;
     External: http://137.108.5.43:8100, http://192.168.56.1:8100&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Let Behat launch the app environment ====&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$CFG-&amp;gt;behat_ionic_dirroot = &#039;/path/to/app/workspace/moodlemobile2&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This may be sufficient, but you need to be aware of a couple of facts about the Ionic server used for app testing:&lt;br /&gt;
&lt;br /&gt;
* Depending on your computer, it may take about 3 minutes to start up. &lt;br /&gt;
* The server uses about 1GB RAM.&lt;br /&gt;
&lt;br /&gt;
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&#039;t restart each time.&lt;br /&gt;
&lt;br /&gt;
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).&lt;br /&gt;
&lt;br /&gt;
== Browser profiles ==&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
* See [[Running acceptance test]] for more information on profiles.&lt;br /&gt;
&lt;br /&gt;
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&#039;t waste time trying to run the app tests in each one.&lt;br /&gt;
&lt;br /&gt;
== Behat init ==&lt;br /&gt;
&lt;br /&gt;
After you have set up the config.php, you will need to re-run Behat init:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
php admin/tool/behat/cli/init.php&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is necessary because by default, Behat won&#039;t run app tests (those with @app tag) at all, since you didn&#039;t have it configured.&lt;br /&gt;
&lt;br /&gt;
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).&lt;br /&gt;
&lt;br /&gt;
* 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.)&lt;br /&gt;
* 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&#039;t. (This version detection only works with app version 3.6.1 and above; for older versions you must specify behat_ionic_dirroot.)&lt;br /&gt;
&lt;br /&gt;
The detected version number will be displayed in the output from the init command:&lt;br /&gt;
&lt;br /&gt;
 $ php admin/tool/behat/cli/init.php&lt;br /&gt;
 You are already using composer version 1.8.4 (stable channel).&lt;br /&gt;
 Loading composer repositories with package information&lt;br /&gt;
 Installing dependencies (including require-dev) from lock file&lt;br /&gt;
 Nothing to install or update&lt;br /&gt;
 Generating autoload files&lt;br /&gt;
 Behat test environment already installed&lt;br /&gt;
 &#039;&#039;&#039;Configured app tests for version 3.6.1&#039;&#039;&#039;&lt;br /&gt;
 2.5 behat profile detected, automatically converted to current 3.x format&lt;br /&gt;
 Acceptance tests environment enabled on http://localhost/core-moodle-github, to run the tests use:&lt;br /&gt;
 vendor/bin/behat --config C:/mylocation/behat/behat.yml&lt;br /&gt;
&lt;br /&gt;
== Running Behat ==&lt;br /&gt;
&lt;br /&gt;
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 &amp;lt;tt&amp;gt;--profile=chrome&amp;lt;/tt&amp;gt;.)&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
== Writing tests ==&lt;br /&gt;
&lt;br /&gt;
This page assumes you already know all about [[Writing acceptance tests]] in general.&lt;br /&gt;
&lt;br /&gt;
=== Test structure ===&lt;br /&gt;
&lt;br /&gt;
* Mobile app test scenarios should be marked &amp;lt;tt&amp;gt;@app&amp;lt;/tt&amp;gt; and &amp;lt;tt&amp;gt;@javascript&amp;lt;/tt&amp;gt; in addition to any other tags that may be required.&lt;br /&gt;
* If creating a feature file specifically for app tests, call it &amp;lt;tt&amp;gt;app_whatever.feature&amp;lt;/tt&amp;gt; (i.e. use the &amp;lt;tt&amp;gt;app_&amp;lt;/tt&amp;gt; prefix). This is not technically required, it&#039;s just for consistency.&lt;br /&gt;
&lt;br /&gt;
You are writing a normal Behat test and this is likely to require background steps similar to any other Moodle Behat test, for example &amp;lt;tt&amp;gt;the following &amp;quot;courses&amp;quot; exist&amp;lt;/tt&amp;gt;, and so on.&lt;br /&gt;
&lt;br /&gt;
=== Start the app ===&lt;br /&gt;
&lt;br /&gt;
Once all necessary Moodle configuration steps (creating courses, users, groups, etc.) are done, use this Behat step to start the app:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;Given &#039;&#039;&#039;I enter the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This will:&lt;br /&gt;
&lt;br /&gt;
* Set up all the Moodle server settings to allow the mobile app to connect.&lt;br /&gt;
* Launch Ionic if necessary&lt;br /&gt;
* Restart the browser. This is needed to ensure it doesn&#039;t contain any stored data from previous app testing.&lt;br /&gt;
* Set the browser to a suitable phone size (you can change it later if you want a tablet or other size).&lt;br /&gt;
* Open the Ionic server address in the test Chrome browser.&lt;br /&gt;
* Install necessary JavaScript code in the page that supports Behat testing. &lt;br /&gt;
* Automatically enter the server URL into the app if necessary.&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
You can use this step even when you are already in the app; this will restart it.&lt;br /&gt;
&lt;br /&gt;
=== Log in to the app ===&lt;br /&gt;
&lt;br /&gt;
To log in:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;When &#039;&#039;&#039;I log in as &amp;quot;student1&amp;quot;&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Actions ===&lt;br /&gt;
&lt;br /&gt;
All the other app-specific Behat steps end with the words &#039;in the app&#039; to distinguish them from the normal steps. &lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And &#039;&#039;&#039;I press &amp;quot;Course 1&amp;quot; in the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This finds an element which contains either the visible text, or Aria label, &#039;Course 1&#039; and clicks it. It should work for links, buttons and similar. &lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
For buttons that are icons with no text, you can specify them using the &#039;aria-label&#039; 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.)&lt;br /&gt;
&lt;br /&gt;
You can press the main (bottom) menu buttons using this step. For example, the home button icon has the label &#039;home&#039;.&lt;br /&gt;
&lt;br /&gt;
* 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.&lt;br /&gt;
* 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.)&lt;br /&gt;
* If the item you try to press is a label for some other form field (using &amp;lt;tt&amp;gt;ion-label&amp;lt;/tt&amp;gt; and the &amp;lt;tt&amp;gt;aria-labelled-by&amp;lt;/tt&amp;gt; attribute) then it will actually press the field; this is useful in the settings menus.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And &#039;&#039;&#039;I press &amp;quot;Course 1&amp;quot; near &amp;quot;Unique text&amp;quot; in the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
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 (&#039;Unique text&#039; in this example) should be some text that is unique on the page. The system will press the instance of &#039;Course 1&#039; that is nearest to the supplied unique text.&lt;br /&gt;
&lt;br /&gt;
(This is intended as a simpler alternative to the standard Behat steps that use the word &#039;in&#039;, such as &amp;lt;tt&amp;gt;I click on &amp;quot;X&amp;quot; &amp;quot;thing&amp;quot; in &amp;quot;Y&amp;quot; &amp;quot;css_element&amp;quot;&amp;lt;/tt&amp;gt;. Those steps are complex and can be difficult to use. This one is not as generic but hopefully will handle most circumstances.)&lt;br /&gt;
&lt;br /&gt;
* 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.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And &#039;&#039;&#039;I set the field &amp;quot;field name&amp;quot; to &amp;quot;text value&amp;quot; in the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
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).&lt;br /&gt;
&lt;br /&gt;
This works with single-line text fields, multi-line text fields with rich text editor switched off (textarea) and rich-text-editor fields.&lt;br /&gt;
&lt;br /&gt;
* 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.&lt;br /&gt;
* When used with a rich-text editor, you can include HTML tags in the value if necessary.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And &#039;&#039;&#039;I press the back button in the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And &#039;&#039;&#039;I press the main menu button in the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And &#039;&#039;&#039;I press the page menu button in the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
These steps will press, respectively:&lt;br /&gt;
&lt;br /&gt;
* The back button (the left pointing arrow at top left of the app).&lt;br /&gt;
* The main menu button (the &#039;...&#039; icon at bottom right of the app).&lt;br /&gt;
* The page menu button, if present (the &#039;...&#039; icon at top right of the app).&lt;br /&gt;
&lt;br /&gt;
Note that both the main menu and page menu use a &#039;more&#039; icon so they are annoying to activate with the generic press command.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And I switch to the browser tab opened by the app&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;And I close the browser tab opened by the app&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
These two steps are necessary if you want to test the transition between the app and browser (e.g. test &#039;Open in browser&#039; links). For example, after pressing &#039;Open in browser&#039; 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.&lt;br /&gt;
&lt;br /&gt;
=== Tests ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;tt&amp;gt;Then &#039;&#039;&#039;the header should be &amp;quot;Course 1&amp;quot; in the app&#039;&#039;&#039;&amp;lt;/tt&amp;gt; &lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
For this scenario, &amp;lt;tt&amp;gt;I should see&amp;lt;/tt&amp;gt; would also work, but this allows you to specifically check the header as opposed to the text appearing elsewhere on the page.&lt;br /&gt;
&lt;br /&gt;
=== Standard test steps ===&lt;br /&gt;
&lt;br /&gt;
You can use all the normal Moodle Behat test steps while carrying out app testing, but some of them don&#039;t work very well. The app has a complex DOM and previous pages that are &#039;back&#039; 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&#039;re not even on.&lt;br /&gt;
&lt;br /&gt;
==== Before the app starts ====&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
==== Useful, working steps ====&lt;br /&gt;
&lt;br /&gt;
* &amp;lt;tt&amp;gt;I should see&amp;lt;/tt&amp;gt; and &amp;lt;tt&amp;gt;I should not see&amp;lt;/tt&amp;gt; are very useful for checking results.&lt;br /&gt;
* &amp;lt;tt&amp;gt;I change viewport size to &amp;quot;640x360&amp;quot;&amp;lt;/tt&amp;gt; is a useful step if you need to simulate switching between portrait and landscape formats.&lt;br /&gt;
* &amp;lt;tt&amp;gt;I pause&amp;lt;/tt&amp;gt; works and is very useful to debug your scenario.&lt;br /&gt;
&lt;br /&gt;
==== Problematic steps ====&lt;br /&gt;
&lt;br /&gt;
* The &amp;lt;tt&amp;gt;I reload the page&amp;lt;/tt&amp;gt; step does not work correctly in the app and may leave your test in a mess. Use &amp;lt;tt&amp;gt;I enter the app&amp;lt;/tt&amp;gt; if you want to reload the app.&lt;br /&gt;
&lt;br /&gt;
=== Leaving the app ===&lt;br /&gt;
&lt;br /&gt;
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 &amp;lt;tt&amp;gt;I am on site homepage&amp;lt;/tt&amp;gt; or &amp;lt;tt&amp;gt;I am on &amp;quot;Course 1&amp;quot; course homepage&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== A complete example ===&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
@app @javascript&lt;br /&gt;
Feature: Test app (demo)&lt;br /&gt;
  In order to test something in the app&lt;br /&gt;
  As a developer&lt;br /&gt;
  I need for this test script to run the app&lt;br /&gt;
&lt;br /&gt;
  Background:&lt;br /&gt;
    Given the following &amp;quot;courses&amp;quot; exist:&lt;br /&gt;
      | fullname | shortname |&lt;br /&gt;
      | Course 1 | C1        |&lt;br /&gt;
    And the following &amp;quot;users&amp;quot; exist:&lt;br /&gt;
      | username |&lt;br /&gt;
      | student1 |&lt;br /&gt;
    And the following &amp;quot;course enrolments&amp;quot; exist:&lt;br /&gt;
      | user     | course | role    |&lt;br /&gt;
      | student1 | C1     | student |&lt;br /&gt;
&lt;br /&gt;
  Scenario: Try going into the course&lt;br /&gt;
    When I enter the app&lt;br /&gt;
    And I log in as &amp;quot;student1&amp;quot;&lt;br /&gt;
    And I press &amp;quot;Course 1&amp;quot; near &amp;quot;Course overview&amp;quot; in the app&lt;br /&gt;
    Then the header should be &amp;quot;Course 1&amp;quot; in the app&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Limitations ==&lt;br /&gt;
&lt;br /&gt;
I have split the limitations of this approach into three categories, below.&lt;br /&gt;
&lt;br /&gt;
=== Fundamental limitations ===&lt;br /&gt;
&lt;br /&gt;
* 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&#039;t very good.)&lt;br /&gt;
* Device features such as the camera cannot be tested, because tests run in a browser and not on a device.&lt;br /&gt;
&lt;br /&gt;
It&#039;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.&lt;br /&gt;
&lt;br /&gt;
=== Extra steps that might be needed ===&lt;br /&gt;
&lt;br /&gt;
* There is no obvious way to attach files.&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Testing the app itself ===&lt;br /&gt;
&lt;br /&gt;
This system can absolutely be used to test features built into the app as well a plugins. &lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
A future extension of this feature could use the behat_ionic_dirroot variable and automatically include feature files from a directory within the app&#039;s source tree. I think this would probably be quite simple but I have not yet tried it.&lt;br /&gt;
&lt;br /&gt;
== Advanced ==&lt;br /&gt;
&lt;br /&gt;
=== Versioning ===&lt;br /&gt;
&lt;br /&gt;
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).&lt;br /&gt;
&lt;br /&gt;
For these situations:&lt;br /&gt;
&lt;br /&gt;
* In addition to the @app tag, add a version-specific tag to your scenario or feature.&lt;br /&gt;
* There are two types of tag: &#039;&#039;&#039;@app_from3.7&#039;&#039;&#039; (include for every app version from 3.7 and newer) or &#039;&#039;&#039;@app_upto3.6.3&#039;&#039;&#039; (include for every app version up to 3.6.3, but not after that).&lt;br /&gt;
* You can use a two-digit or three-digit version number (3.6 or 3.6.1).&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Testing against multiple app versions ===&lt;br /&gt;
&lt;br /&gt;
If you need to run tests against multiple versions of the mobile app, you can do this in two ways:&lt;br /&gt;
&lt;br /&gt;
# Update the code in the mobile app workspace (check out a different version). Then re-run Behat init and run the Behat tests again.&lt;br /&gt;
# 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.&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
=== Debugging tests ===&lt;br /&gt;
&lt;br /&gt;
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:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
VM649:391 BEHAT: 17:45:15.477 Action - Set field Username to: student2&lt;br /&gt;
VM649:391 BEHAT: 17:45:15.480 PENDING+: DELAY,dom-mutation&lt;br /&gt;
VM649:391 BEHAT: 17:45:15.982 PENDING-: DELAY&lt;br /&gt;
VM649:391 BEHAT: 17:45:16.28 PENDING-: &lt;br /&gt;
VM649:391 BEHAT: 17:45:16.98 Action - Set field Password to: student2&lt;br /&gt;
VM649:391 BEHAT: 17:45:16.106 PENDING+: DELAY,dom-mutation&lt;br /&gt;
VM649:391 BEHAT: 17:45:16.607 PENDING-: DELAY&lt;br /&gt;
VM649:391 BEHAT: 17:45:16.653 PENDING-: &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
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&#039;re not quite sure what command would work. Here are examples of the most useful commands:&lt;br /&gt;
&lt;br /&gt;
* &amp;lt;tt&amp;gt;behat.setField(&#039;Password&#039;, &#039;student2&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
* &amp;lt;tt&amp;gt;behat.press(&#039;Log in&#039;, &#039;Forgotten&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
* &amp;lt;tt&amp;gt;behat.pressStandard(&#039;back&#039;)&amp;lt;/tt&amp;gt;&lt;br /&gt;
&lt;br /&gt;
There are a few other functions in the &#039;behat&#039; object; try using the browser&#039;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].&lt;br /&gt;
&lt;br /&gt;
==Useful tips==&lt;br /&gt;
&lt;br /&gt;
# Make sure you added $CFG-&amp;gt;behat_ionic_wwwroot = &#039;http://localhost:8100&#039;; to your config.php.&lt;br /&gt;
# 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.)&lt;br /&gt;
# Remember when you need to re-run php admin/tool/behat/cli/init.php from your development code base root. Make sure the message &#039;Configured app tests for version 3.6.1&#039; (or whatever version) appears.&lt;br /&gt;
# 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 &#039;integration&#039; branch.&lt;br /&gt;
# The message &#039;cURL request for &amp;quot;http://localhost:8100/config.json&amp;quot; failed with: Failed to connect to localhost port 8100: Connection refused&#039; means that you have not started the ionic server, or have not waited long enough (several minutes) for it to start).&lt;br /&gt;
# Message &#039;missing config.json&#039; - this should exist in your app code base/www, just re-run ionic serve -b to re-create it.&lt;br /&gt;
# Message &#039;Error The plugins required by this course could not be loaded correctly...&#039; - 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.&lt;br /&gt;
# Message &#039;Fatal error: Maximum execution time of 30 seconds exceeded in...&#039; - 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!&lt;br /&gt;
# Create an unsafe browser link on your desktop. That is, a shortcut with a command like &amp;quot;C:\Program Files (x86)\Google\Chrome\Application\chrome.exe&amp;quot; --allow-file-access-from-files --disable-web-security --user-data-dir  --allow-running-insecure-content&amp;quot;&lt;br /&gt;
&lt;br /&gt;
== Trouble shooting ==&lt;br /&gt;
&lt;br /&gt;
=== Test fails because of the browser language ===&lt;br /&gt;
&lt;br /&gt;
If your operating system is in a different language than English the tests may fail. &lt;br /&gt;
&lt;br /&gt;
Chrome does not have an easy way to force the browser language to English so the best way to solve the issue is forcing the app default language to English.&lt;br /&gt;
&lt;br /&gt;
To do so, just edit the src/config.json file including this attribute: &amp;quot;forcedefaultlanguage&amp;quot;: &amp;quot;en&amp;quot;,&lt;br /&gt;
&lt;br /&gt;
[[Category:Quality Assurance]][[Category:Behat]][[Category:Mobile]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Moodle_3.8_release_notes&amp;diff=57064</id>
		<title>Moodle 3.8 release notes</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Moodle_3.8_release_notes&amp;diff=57064"/>
		<updated>2020-03-11T19:14:31Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* For developers */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Releases]] &amp;gt; {{FULLPAGENAME}}&lt;br /&gt;
 &lt;br /&gt;
&lt;br /&gt;
Release date: 18 November 2019&lt;br /&gt;
&lt;br /&gt;
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&amp;amp;runQuery=true&amp;amp;clear=true the full list of fixed issues in 3.8].&lt;br /&gt;
&lt;br /&gt;
If you are upgrading from a previous version, please see [[:en:Upgrading|Upgrading]] in the user docs.&lt;br /&gt;
&lt;br /&gt;
==Server requirements==&lt;br /&gt;
&lt;br /&gt;
These are just the minimum supported versions. We recommend keeping all of your software and operating systems up-to-date.&lt;br /&gt;
&lt;br /&gt;
* Moodle upgrade:  Moodle 3.2 or later&lt;br /&gt;
* PHP version: minimum PHP 7.1.0 &#039;&#039;Note: minimum PHP version has increased since Moodle 3.6&#039;&#039;. 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]. &lt;br /&gt;
* PHP extension &#039;&#039;&#039;intl&#039;&#039;&#039; is required since Moodle 3.4 (it was recommended in 2.0 onwards) &lt;br /&gt;
&lt;br /&gt;
=== Database requirements ===&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;nicetable&amp;quot;&lt;br /&gt;
|-&lt;br /&gt;
! Database&lt;br /&gt;
! Minimum version&lt;br /&gt;
! Recommended&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.postgresql.org/ PostgreSQL]&lt;br /&gt;
| 9.4&lt;br /&gt;
| 11.x then 12.x in Moodle 3.8.2 onwards&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.mysql.com/ MySQL]&lt;br /&gt;
| 5.6&lt;br /&gt;
| Latest&lt;br /&gt;
|-&lt;br /&gt;
| [https://mariadb.org/ MariaDB]&lt;br /&gt;
| 5.5.31&lt;br /&gt;
| Latest&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]&lt;br /&gt;
| 2012 &#039;&#039;(increased since Moodle 3.7)&#039;&#039;&lt;br /&gt;
| Latest&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]&lt;br /&gt;
| 11.2&lt;br /&gt;
| Latest&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
==Client requirements==&lt;br /&gt;
&lt;br /&gt;
=== Browser support ===&lt;br /&gt;
Moodle is compatible with any standards compliant web browser. We regularly test Moodle with the following browsers:&lt;br /&gt;
&lt;br /&gt;
Desktop:&lt;br /&gt;
* Chrome&lt;br /&gt;
* Firefox&lt;br /&gt;
* Safari&lt;br /&gt;
* Edge&lt;br /&gt;
* Internet Explorer&lt;br /&gt;
&lt;br /&gt;
Mobile:&lt;br /&gt;
* MobileSafari&lt;br /&gt;
* Google Chrome&lt;br /&gt;
&lt;br /&gt;
For the best experience and optimum security, we recommend that you keep your browser up to date.&lt;br /&gt;
&lt;br /&gt;
Note: Legacy browsers with known compatibility issues with Moodle 3.8:&lt;br /&gt;
* Internet Explorer 10 and below&lt;br /&gt;
* Safari 7 and below&lt;br /&gt;
 &lt;br /&gt;
&lt;br /&gt;
==Major features==&lt;br /&gt;
&lt;br /&gt;
===Analytics===&lt;br /&gt;
&lt;br /&gt;
* MDL-64739 - Analytics models may be restricted to category or course contexts&lt;br /&gt;
* MDL-65588 - Insights about students who have not logged in recently&lt;br /&gt;
* MDL-65562 - Report on the actions executed by users on predictions&lt;br /&gt;
* MDL-65633 - Allow targets to limit the analysis interval to a specific interface or parent class.&lt;br /&gt;
* MDL-66234 - Extra garbage collection for analytics&lt;br /&gt;
* MDL-66254 - Require enrolments to be active for most of the analysis interval&lt;br /&gt;
* MDL-62191 - Add bulk actions for analytics&#039; insights&lt;br /&gt;
* MDL-66536 - Insight notifications improvements&lt;br /&gt;
* MDL-60949 - Analytics models should be sorted by name and not last modified&lt;br /&gt;
* MDL-66004 - Allow the Python machine learning backend to run from a separate server&lt;br /&gt;
* MDL-58992 - Add multi-class capabilities to prediction processors&lt;br /&gt;
* MDL-65585 - Global on/off switch for analytics&lt;br /&gt;
&lt;br /&gt;
===H5P integration===&lt;br /&gt;
&lt;br /&gt;
* MDL-66388 - Create a new button in Atto to add H5P content in anywhere from hp5.com and h5p.org external URLs&lt;br /&gt;
* MDL-66398 - Improve H5P filter to allow internal H5P content URLs&lt;br /&gt;
* MDL-66593 - Implement backup and restore process for H5P content&lt;br /&gt;
* MDL-67059 - Add Admin UI to manually upload H5P content-type libraries&lt;br /&gt;
* MDL-67057 - Create a capability to update H5P content-type libraries&lt;br /&gt;
* MDL-67058 - Create a task to install H5P content-type libraries&lt;br /&gt;
* MDL-66609 - Create the basic skeleton, library and interfaces for rendering H5P content&lt;br /&gt;
* MDL-66399 - Improve H5P Atto button to upload content&lt;br /&gt;
* MDL-66397 - Create a new filter to convert h5p.com and h5p.org URLs to embed code&lt;br /&gt;
&lt;br /&gt;
===Forum summary report===&lt;br /&gt;
&lt;br /&gt;
* MDL-66153 - Forum report: Basic skeleton&lt;br /&gt;
* MDL-66298 - Forum summary report option to message selected users&lt;br /&gt;
* MDL-66268 - Groups filter in forum summary report&lt;br /&gt;
* MDL-66373 - Dates filter in forum summary report&lt;br /&gt;
* MDL-66297 - Link forum summary report to export of each user&#039;s post content&lt;br /&gt;
* MDL-66694 - Add columns for word count and character count to the forum summary report&lt;br /&gt;
* MDL-66768 - Add the ability to download the forum summary report&lt;br /&gt;
&lt;br /&gt;
===Forum export===&lt;br /&gt;
&lt;br /&gt;
* MDL-66075 - Forum export functionality&lt;br /&gt;
* MDL-66631 - Dates filter in forum export&lt;br /&gt;
* MDL-66808 - Forum export options for human-readable dates and removing HTML&lt;br /&gt;
&lt;br /&gt;
===Forum grading===&lt;br /&gt;
&lt;br /&gt;
* MDL-66074 - Create forum grading interface&lt;br /&gt;
* MDL-66358 - Display grading form in the grading panel&lt;br /&gt;
* MDL-66365 - Add a button to display the entire discussion for a post being graded&lt;br /&gt;
* MDL-67116 - Make &#039;require grade&#039; an activity completion criterion for the forum&lt;br /&gt;
* MDL-66381 - Forum grading user search&lt;br /&gt;
* MDL-66360 - Forum grading option to send notification to student&lt;br /&gt;
* MDL-66906 - Forum view grades option for students&lt;br /&gt;
* MDL-66359 - Support restricting the user list to a specific group&lt;br /&gt;
&lt;br /&gt;
===Forum UI improvements===&lt;br /&gt;
&lt;br /&gt;
* MDL-66477 - Create settings side drawer for new discussion view&lt;br /&gt;
* MDL-64821 - Create new discussion view for forum&lt;br /&gt;
* MDL-66481 - Update display of discussion in discussion list table&lt;br /&gt;
* MDL-65129 - Search starred discussions only option in forum advanced search&lt;br /&gt;
&lt;br /&gt;
===Assignment===&lt;br /&gt;
&lt;br /&gt;
* MDL-63349 - Assignment: Annotate PDF - Rotate submitted image automatically&lt;br /&gt;
* MDL-66537 - Annotate PDF - Right-to-left UI - The rotate buttons order is confusing&lt;br /&gt;
* MDL-63878 - Enable the saving and printing of annotated PDFs from previous attempts&lt;br /&gt;
* MDL-64811 - Assignment: Add warning about students falling into Default group if group submissions are enabled but not required&lt;br /&gt;
* MDL-65797 - Performance improvements for user / group overrides for mod assign&lt;br /&gt;
&lt;br /&gt;
===Question bank===&lt;br /&gt;
&lt;br /&gt;
* MDL-66553 - Display ID number and tags in the question bank UI&lt;br /&gt;
* MDL-66816 - Question bank: replace the row of edit icons with an Edit menu&lt;br /&gt;
* MDL-67153 - Allow question types to add extra actions to the Question bank edit menu&lt;br /&gt;
&lt;br /&gt;
===Course relative dates (experimental)===&lt;br /&gt;
&lt;br /&gt;
* MDL-66147 - Assignment due date relative to the student course start date&lt;br /&gt;
* MDL-66144 - Weeks format relative dates&lt;br /&gt;
* MDL-66143 - [[:en:Course relative dates|Course relative dates]] mode setting&lt;br /&gt;
* MDL-66148 - Option to override the assignment due date in a relative dates course&lt;br /&gt;
&lt;br /&gt;
===Course overview===&lt;br /&gt;
&lt;br /&gt;
* MDL-64901 - block_myoverview: Add admin setting to control the available layouts&lt;br /&gt;
* MDL-66016 - An admin can set which filters are available for users to select in their Dashboard course overview&lt;br /&gt;
* MDL-66017 - An admin can specify a course custom field as a filter for users to select in their Dashboard course overview&lt;br /&gt;
* MDL-63612 - Course card pattern colours may be specified by an admin&lt;br /&gt;
* MDL-65621 - Courses with course visibility set to hide should be labelled &#039;Hidden from students&#039; in the course overview&lt;br /&gt;
* MDL-64860 - block_myoverview: Improve pagination widget&lt;br /&gt;
* MDL-64094 - Change &#039;Hidden&#039; to &#039;Removed from view&#039; in the course overview&lt;br /&gt;
&lt;br /&gt;
===Emojis===&lt;br /&gt;
&lt;br /&gt;
* MDL-65896 - Add emojis to messaging&lt;br /&gt;
* MDL-46779 - Atto should support full emoji&lt;br /&gt;
&lt;br /&gt;
===Usability improvements===&lt;br /&gt;
&lt;br /&gt;
* MDL-34498 - Session Timeout alert&lt;br /&gt;
* MDL-61043 - Provide a more consistent and better way of selecting and deselecting all items in a list&lt;br /&gt;
* MDL-48610 - Show alphabet filter in grader report even when there are fewer than 100 users&lt;br /&gt;
* MDL-38555 - Forms do not prevent same data submission multiple times&lt;br /&gt;
* MDL-59639 - Browser back button should work as expected in the administration menu with Boost theme&lt;br /&gt;
* MDL-57208 - Let users set their default homepage&lt;br /&gt;
* MDL-66178 - Participants list - Filter users with no roles&lt;br /&gt;
* MDL-65671 - Calendar view selector enables users to switch between month, day and upcoming events&lt;br /&gt;
* MDL-66563 - Improve drag and drop question accessibility in high-contrast mode&lt;br /&gt;
* MDL-64032 - The UI for setting enrolment end date/duration should be consistent&lt;br /&gt;
* MDL-65406 - Boost Theme accessibility: Nav drawer should be marked up as list&lt;br /&gt;
* MDL-65915 - Better progress display while re-grading quiz attempts&lt;br /&gt;
* MDL-67048 - Drag and drop upload progressbar invert inner and outer&lt;br /&gt;
&lt;br /&gt;
==Other highlights==&lt;br /&gt;
&lt;br /&gt;
===Functional changes===&lt;br /&gt;
&lt;br /&gt;
* MDL-64745 - Administrative setting to show/not show &amp;quot;hide&amp;quot; feature in online users block&lt;br /&gt;
* MDL-62835 - The description should be displayed when viewing a Book, Lesson or IMS content package&lt;br /&gt;
* MDL-66496 - Option to include author information when importing entries into a database activity&lt;br /&gt;
* MDL-66740 - Make &amp;quot;course request&amp;quot; capability category context instead of system context&lt;br /&gt;
* MDL-65093 - Users should be informed that they can&#039;t block a user who has permission to message all users&lt;br /&gt;
* MDL-64002 - Add send message buffering&lt;br /&gt;
* MDL-66226 - Show plain text in Messages summary pane&lt;br /&gt;
* MDL-61649 - Several core emails provide only text format&lt;br /&gt;
* MDL-35773 - Include files option in backup settings&lt;br /&gt;
* MDL-63453 - VideoJS upgrade to 7.6.5 including HTTP Live Streaming (HLS) and Dynamic Adaptive Streaming over HTTP (MPEG-DASH) support&lt;br /&gt;
* MDL-56549 - Add support for FLAC files&lt;br /&gt;
* MDL-62836 - Make awarding badges groups/groupings compliant&lt;br /&gt;
* MDL-60916 - Global Search: Replace course search form with global search&lt;br /&gt;
* MDL-64438 - Display course category in course related block&lt;br /&gt;
* MDL-66326 - Global search: Delete from search index when courses are deleted&lt;br /&gt;
* MDL-65183 - block_timeline can cause JSON parse error on dashboard when activities are saved with newline characters&lt;br /&gt;
* MDL-66612 - Calendar course event icon is different from course icon&lt;br /&gt;
* MDL-66775 - Add new Mobile setting for forcing a minimum app version to access the site&lt;br /&gt;
* MDL-66375 - Option to disable the &amp;quot;Forgotten password&amp;quot; feature in the app&lt;br /&gt;
* MDL-66753 - The People block is no longer needed and should be removed from core&lt;br /&gt;
&lt;br /&gt;
===For administrators===&lt;br /&gt;
&lt;br /&gt;
* MDL-66034 - Log role changes in more detail&lt;br /&gt;
* MDL-66570 - Allow disabling of cron output when capturing logs&lt;br /&gt;
* MDL-61804 - Let the admin control if lists of courses should be pre-sorted by visibility or not&lt;br /&gt;
* MDL-66133 - Let the administrator configure which user filters are shown by default&lt;br /&gt;
* MDL-63643 - Add ability to search/filter users by Last IP Address&lt;br /&gt;
* MDL-66119 - Disable GUI plugin uninstalls (eg $CFG-&amp;gt;uninstallclionly similar to $CFG-&amp;gt;disableupdateautodeploy)&lt;br /&gt;
* MDL-65201 - Automated backup course ordering&lt;br /&gt;
* MDL-65404 - Add column for enrol start dates to Upload users CSV&lt;br /&gt;
* MDL-40669 - Upload users via text file should include the optional user field &#039;disable notifications&#039;&lt;br /&gt;
* MDL-66705 - Add an example csv file for bulk uploading of users&lt;br /&gt;
* MDL-59470 - Option to duplicate a user tour&lt;br /&gt;
* MDL-65622 - Add a new event when a grade item has been created&lt;br /&gt;
* MDL-65369 - Include changed course settings in course_updated event&lt;br /&gt;
* MDL-65492 - Cache admin UI: make it easy re-purge the cache you just purged&lt;br /&gt;
* MDL-63127 - Redis Cache: implement compression&lt;br /&gt;
* MDL-66428 - Allow Redis cache to use PHP extension Zstd&lt;br /&gt;
* MDL-46317 - Private files space setting should use MB not Bytes&lt;br /&gt;
* MDL-7339 - Change &#039;Open to Google&#039; setting to &#039;Open to search engines&#039;&lt;br /&gt;
* MDL-65208 - Add cli upgrade option to test if an upgrade is required&lt;br /&gt;
* MDL-58439 - Admin pages login as guest and then throw Access denied error (should prompt for login) require_admin()&lt;br /&gt;
&lt;br /&gt;
==For developers==&lt;br /&gt;
&lt;br /&gt;
* MDL-66675 - New &amp;lt;tt&amp;gt;$CFG-&amp;gt;behat_pause_on_fail&amp;lt;/tt&amp;gt; option added&lt;br /&gt;
* MDL-46267 - The &amp;lt;tt&amp;gt;$CFG-&amp;gt;httpswwwroot&amp;lt;/tt&amp;gt; was removed&lt;br /&gt;
* MDL-66335 - New steps to navigate straight to any plugin web page. Plugins must implement their own resolver between page types and URLs.&lt;br /&gt;
* MDL-65349 - Profiling included and excluded URLs now are matched from start. Some adjustments may be needed.&lt;br /&gt;
* MDL-66633 - Quiz: quiz attempt API should let you create an attempt for a different user&lt;br /&gt;
* MDL-66709 - Components other than activity modules should be able to backup and restore question attempt data&lt;br /&gt;
* MDL-66754 - Question engine: report methods should not require a list of slots&lt;br /&gt;
* MDL-62497 - Add a new transpilation tool for ES6&lt;br /&gt;
* MDL-50346 - Remove the restriction to forbid subdirectories in the templates directory&lt;br /&gt;
* MDL-66327 - $DB-&amp;gt;get_records uses a lot of Peak RAM (with Postgres)&lt;br /&gt;
* MDL-66173 - Add hooks to extend all forms with /login/&lt;br /&gt;
* MDL-66367 - Caching of templates should use a new templaterev variable&lt;br /&gt;
* MDL-66304 - Allow support for xsendfile in alternative_file_system_class independently of local files&lt;br /&gt;
* MDL-66166 - Improve the moodlebot user agent and expose a function for plugins to use&lt;br /&gt;
* MDL-65646 - Move dependencies and subplugins to JSON&lt;br /&gt;
* MDL-55751 - Remove the CSS chunker from Moodle&lt;br /&gt;
* MDL-65438 - Allow themes to alter the core css url&#039;s&lt;br /&gt;
* MDL-65747 - Removed unused Pear_Crypt_CHAP library&lt;br /&gt;
* MDL-65762 - Upgrade Box::Spout to 3.x - Warning! Spout 3.x has a breaking API changes compared to 2.x which was used in Moodle &amp;lt;= 3.7.x. If you are using Spout directly, not through moodle&#039;s wrappers, then you need to read https://github.com/box/spout/blob/0f0bf648024040d21c6bd9930299265e8fc42550/UPGRADE-3.0.md.&lt;br /&gt;
&lt;br /&gt;
===Web services additions and updates===&lt;br /&gt;
&lt;br /&gt;
* MDL-65794 - Make some web service calls idempotent over http GET&lt;br /&gt;
* MDL-67043 - Web service to enable H5P offline access in the Moodle app&lt;br /&gt;
* MDL-64254 - New Web Services for updating a forum post (or a discussion topic post)&lt;br /&gt;
* MDL-65017 - New web service to delete forum posts&lt;br /&gt;
* MDL-64588 - New web services for adding and deleting comments&lt;br /&gt;
* MDL-66376 - Enforce app security by using tokenpluginfile.php instead webservice/pluginfile.php&lt;br /&gt;
* MDL-65400 - Blocks Web Services (for course and dashboard) should return the block settings&lt;br /&gt;
&lt;br /&gt;
===Component API upgrades===&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/admin/upgrade.txt admin/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/analytics/upgrade.txt analytics/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/blocks/recentlyaccessedcourses/upgrade.txt blocks/recentlyaccessedcourses/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/blocks/starredcourses/upgrade.txt blocks/starredcourses/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/blocks/upgrade.txt blocks/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/cache/upgrade.txt cache/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/calendar/upgrade.txt calendar/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/comment/upgrade.txt comment/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/format/upgrade.txt course/format/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/upgrade.txt course/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/customfield/field/upgrade.txt customfield/field/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/enrol/ldap/upgrade.txt enrol/ldap/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/enrol/upgrade.txt enrol/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/mlbackend/php/upgrade.txt lib/mlbackend/php/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/mlbackend/python/upgrade.txt lib/mlbackend/python/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/upgrade.txt lib/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/media/upgrade.txt media/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/message/upgrade.txt message/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/assign/upgrade.txt mod/assign/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/book/upgrade.txt mod/book/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/feedback/upgrade.txt mod/feedback/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/forum/upgrade.txt mod/forum/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/glossary/upgrade.txt mod/glossary/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/lti/upgrade.txt mod/lti/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/quiz/report/upgrade.txt mod/quiz/report/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/upgrade.txt mod/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/wiki/upgrade.txt mod/wiki/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/workshop/upgrade.txt mod/workshop/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/question/type/upgrade.txt question/type/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/question/upgrade.txt question/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/search/upgrade.txt search/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/theme/upgrade.txt theme/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/webservice/upgrade.txt webservice/upgrade.txt]&lt;br /&gt;
&lt;br /&gt;
==See also==&lt;br /&gt;
*[[Moodle 3.7 release notes]]&lt;br /&gt;
 &lt;br /&gt;
[[Category:Release notes]]&lt;br /&gt;
[[Category:Moodle 3.8]]&lt;br /&gt;
 &lt;br /&gt;
[[fr:Notes de mise à jour de Moodle 3.8]]&lt;br /&gt;
[[es:Notas de Moodle 3.8]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Moodle_3.8_release_notes&amp;diff=56987</id>
		<title>Moodle 3.8 release notes</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Moodle_3.8_release_notes&amp;diff=56987"/>
		<updated>2020-03-06T18:10:00Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* Usability improvements */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;[[Releases]] &amp;gt; {{FULLPAGENAME}}&lt;br /&gt;
 &lt;br /&gt;
&lt;br /&gt;
Release date: 18 November 2019&lt;br /&gt;
&lt;br /&gt;
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&amp;amp;runQuery=true&amp;amp;clear=true the full list of fixed issues in 3.8].&lt;br /&gt;
&lt;br /&gt;
If you are upgrading from a previous version, please see [[:en:Upgrading|Upgrading]] in the user docs.&lt;br /&gt;
&lt;br /&gt;
==Server requirements==&lt;br /&gt;
&lt;br /&gt;
These are just the minimum supported versions. We recommend keeping all of your software and operating systems up-to-date.&lt;br /&gt;
&lt;br /&gt;
* Moodle upgrade:  Moodle 3.2 or later&lt;br /&gt;
* PHP version: minimum PHP 7.1.0 &#039;&#039;Note: minimum PHP version has increased since Moodle 3.6&#039;&#039;. 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]. &lt;br /&gt;
* PHP extension &#039;&#039;&#039;intl&#039;&#039;&#039; is required since Moodle 3.4 (it was recommended in 2.0 onwards) &lt;br /&gt;
&lt;br /&gt;
=== Database requirements ===&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;nicetable&amp;quot;&lt;br /&gt;
|-&lt;br /&gt;
! Database&lt;br /&gt;
! Minimum version&lt;br /&gt;
! Recommended&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.postgresql.org/ PostgreSQL]&lt;br /&gt;
| 9.4&lt;br /&gt;
| 11.x then 12.x in Moodle 3.8.2 onwards&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.mysql.com/ MySQL]&lt;br /&gt;
| 5.6&lt;br /&gt;
| Latest&lt;br /&gt;
|-&lt;br /&gt;
| [https://mariadb.org/ MariaDB]&lt;br /&gt;
| 5.5.31&lt;br /&gt;
| Latest&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]&lt;br /&gt;
| 2012 &#039;&#039;(increased since Moodle 3.7)&#039;&#039;&lt;br /&gt;
| Latest&lt;br /&gt;
|-&lt;br /&gt;
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]&lt;br /&gt;
| 11.2&lt;br /&gt;
| Latest&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
==Client requirements==&lt;br /&gt;
&lt;br /&gt;
=== Browser support ===&lt;br /&gt;
Moodle is compatible with any standards compliant web browser. We regularly test Moodle with the following browsers:&lt;br /&gt;
&lt;br /&gt;
Desktop:&lt;br /&gt;
* Chrome&lt;br /&gt;
* Firefox&lt;br /&gt;
* Safari&lt;br /&gt;
* Edge&lt;br /&gt;
* Internet Explorer&lt;br /&gt;
&lt;br /&gt;
Mobile:&lt;br /&gt;
* MobileSafari&lt;br /&gt;
* Google Chrome&lt;br /&gt;
&lt;br /&gt;
For the best experience and optimum security, we recommend that you keep your browser up to date.&lt;br /&gt;
&lt;br /&gt;
Note: Legacy browsers with known compatibility issues with Moodle 3.8:&lt;br /&gt;
* Internet Explorer 10 and below&lt;br /&gt;
* Safari 7 and below&lt;br /&gt;
 &lt;br /&gt;
&lt;br /&gt;
==Major features==&lt;br /&gt;
&lt;br /&gt;
===Analytics===&lt;br /&gt;
&lt;br /&gt;
* MDL-64739 - Analytics models may be restricted to category or course contexts&lt;br /&gt;
* MDL-65588 - Insights about students who have not logged in recently&lt;br /&gt;
* MDL-65562 - Report on the actions executed by users on predictions&lt;br /&gt;
* MDL-65633 - Allow targets to limit the analysis interval to a specific interface or parent class.&lt;br /&gt;
* MDL-66234 - Extra garbage collection for analytics&lt;br /&gt;
* MDL-66254 - Require enrolments to be active for most of the analysis interval&lt;br /&gt;
* MDL-62191 - Add bulk actions for analytics&#039; insights&lt;br /&gt;
* MDL-66536 - Insight notifications improvements&lt;br /&gt;
* MDL-60949 - Analytics models should be sorted by name and not last modified&lt;br /&gt;
* MDL-66004 - Allow the Python machine learning backend to run from a separate server&lt;br /&gt;
* MDL-58992 - Add multi-class capabilities to prediction processors&lt;br /&gt;
* MDL-65585 - Global on/off switch for analytics&lt;br /&gt;
&lt;br /&gt;
===H5P integration===&lt;br /&gt;
&lt;br /&gt;
* MDL-66388 - Create a new button in Atto to add H5P content in anywhere from hp5.com and h5p.org external URLs&lt;br /&gt;
* MDL-66398 - Improve H5P filter to allow internal H5P content URLs&lt;br /&gt;
* MDL-66593 - Implement backup and restore process for H5P content&lt;br /&gt;
* MDL-67059 - Add Admin UI to manually upload H5P content-type libraries&lt;br /&gt;
* MDL-67057 - Create a capability to update H5P content-type libraries&lt;br /&gt;
* MDL-67058 - Create a task to install H5P content-type libraries&lt;br /&gt;
* MDL-66609 - Create the basic skeleton, library and interfaces for rendering H5P content&lt;br /&gt;
* MDL-66399 - Improve H5P Atto button to upload content&lt;br /&gt;
* MDL-66397 - Create a new filter to convert h5p.com and h5p.org URLs to embed code&lt;br /&gt;
&lt;br /&gt;
===Forum summary report===&lt;br /&gt;
&lt;br /&gt;
* MDL-66153 - Forum report: Basic skeleton&lt;br /&gt;
* MDL-66298 - Forum summary report option to message selected users&lt;br /&gt;
* MDL-66268 - Groups filter in forum summary report&lt;br /&gt;
* MDL-66373 - Dates filter in forum summary report&lt;br /&gt;
* MDL-66297 - Link forum summary report to export of each user&#039;s post content&lt;br /&gt;
* MDL-66694 - Add columns for word count and character count to the forum summary report&lt;br /&gt;
* MDL-66768 - Add the ability to download the forum summary report&lt;br /&gt;
&lt;br /&gt;
===Forum export===&lt;br /&gt;
&lt;br /&gt;
* MDL-66075 - Forum export functionality&lt;br /&gt;
* MDL-66631 - Dates filter in forum export&lt;br /&gt;
* MDL-66808 - Forum export options for human-readable dates and removing HTML&lt;br /&gt;
&lt;br /&gt;
===Forum grading===&lt;br /&gt;
&lt;br /&gt;
* MDL-66074 - Create forum grading interface&lt;br /&gt;
* MDL-66358 - Display grading form in the grading panel&lt;br /&gt;
* MDL-66365 - Add a button to display the entire discussion for a post being graded&lt;br /&gt;
* MDL-67116 - Make &#039;require grade&#039; an activity completion criterion for the forum&lt;br /&gt;
* MDL-66381 - Forum grading user search&lt;br /&gt;
* MDL-66360 - Forum grading option to send notification to student&lt;br /&gt;
* MDL-66906 - Forum view grades option for students&lt;br /&gt;
* MDL-66359 - Support restricting the user list to a specific group&lt;br /&gt;
&lt;br /&gt;
===Forum UI improvements===&lt;br /&gt;
&lt;br /&gt;
* MDL-66477 - Create settings side drawer for new discussion view&lt;br /&gt;
* MDL-64821 - Create new discussion view for forum&lt;br /&gt;
* MDL-66481 - Update display of discussion in discussion list table&lt;br /&gt;
* MDL-65129 - Search starred discussions only option in forum advanced search&lt;br /&gt;
&lt;br /&gt;
===Assignment===&lt;br /&gt;
&lt;br /&gt;
* MDL-63349 - Assignment: Annotate PDF - Rotate submitted image automatically&lt;br /&gt;
* MDL-66537 - Annotate PDF - Right-to-left UI - The rotate buttons order is confusing&lt;br /&gt;
* MDL-63878 - Enable the saving and printing of annotated PDFs from previous attempts&lt;br /&gt;
* MDL-64811 - Assignment: Add warning about students falling into Default group if group submissions are enabled but not required&lt;br /&gt;
* MDL-65797 - Performance improvements for user / group overrides for mod assign&lt;br /&gt;
&lt;br /&gt;
===Question bank===&lt;br /&gt;
&lt;br /&gt;
* MDL-66553 - Display ID number and tags in the question bank UI&lt;br /&gt;
* MDL-66816 - Question bank: replace the row of edit icons with an Edit menu&lt;br /&gt;
* MDL-67153 - Allow question types to add extra actions to the Question bank edit menu&lt;br /&gt;
&lt;br /&gt;
===Course relative dates (experimental)===&lt;br /&gt;
&lt;br /&gt;
* MDL-66147 - Assignment due date relative to the student course start date&lt;br /&gt;
* MDL-66144 - Weeks format relative dates&lt;br /&gt;
* MDL-66143 - [[:en:Course relative dates|Course relative dates]] mode setting&lt;br /&gt;
* MDL-66148 - Option to override the assignment due date in a relative dates course&lt;br /&gt;
&lt;br /&gt;
===Course overview===&lt;br /&gt;
&lt;br /&gt;
* MDL-64901 - block_myoverview: Add admin setting to control the available layouts&lt;br /&gt;
* MDL-66016 - An admin can set which filters are available for users to select in their Dashboard course overview&lt;br /&gt;
* MDL-66017 - An admin can specify a course custom field as a filter for users to select in their Dashboard course overview&lt;br /&gt;
* MDL-63612 - Course card pattern colours may be specified by an admin&lt;br /&gt;
* MDL-65621 - Courses with course visibility set to hide should be labelled &#039;Hidden from students&#039; in the course overview&lt;br /&gt;
* MDL-64860 - block_myoverview: Improve pagination widget&lt;br /&gt;
* MDL-64094 - Change &#039;Hidden&#039; to &#039;Removed from view&#039; in the course overview&lt;br /&gt;
&lt;br /&gt;
===Emojis===&lt;br /&gt;
&lt;br /&gt;
* MDL-65896 - Add emojis to messaging&lt;br /&gt;
* MDL-46779 - Atto should support full emoji&lt;br /&gt;
&lt;br /&gt;
===Usability improvements===&lt;br /&gt;
&lt;br /&gt;
* MDL-34498 - Session Timeout alert&lt;br /&gt;
* MDL-61043 - Provide a more consistent and better way of selecting and deselecting all items in a list&lt;br /&gt;
* MDL-48610 - Show alphabet filter in grader report even when there are fewer than 100 users&lt;br /&gt;
* MDL-38555 - Forms do not prevent same data submission multiple times&lt;br /&gt;
* MDL-59639 - Browser back button should work as expected in the administration menu with Boost theme&lt;br /&gt;
* MDL-57208 - Let users set their default homepage&lt;br /&gt;
* MDL-66178 - Participants list - Filter users with no roles&lt;br /&gt;
* MDL-65671 - Calendar view selector enables users to switch between month, day and upcoming events&lt;br /&gt;
* MDL-66563 - Improve drag and drop question accessibility in high-contrast mode&lt;br /&gt;
* MDL-64032 - The UI for setting enrolment end date/duration should be consistent&lt;br /&gt;
* MDL-65406 - Boost Theme accessibility: Nav drawer should be marked up as list&lt;br /&gt;
* MDL-65915 - Better progress display while re-grading quiz attempts&lt;br /&gt;
* MDL-67048 - Drag and drop upload progressbar invert inner and outer&lt;br /&gt;
&lt;br /&gt;
==Other highlights==&lt;br /&gt;
&lt;br /&gt;
===Functional changes===&lt;br /&gt;
&lt;br /&gt;
* MDL-64745 - Administrative setting to show/not show &amp;quot;hide&amp;quot; feature in online users block&lt;br /&gt;
* MDL-62835 - The description should be displayed when viewing a Book, Lesson or IMS content package&lt;br /&gt;
* MDL-66496 - Option to include author information when importing entries into a database activity&lt;br /&gt;
* MDL-66740 - Make &amp;quot;course request&amp;quot; capability category context instead of system context&lt;br /&gt;
* MDL-65093 - Users should be informed that they can&#039;t block a user who has permission to message all users&lt;br /&gt;
* MDL-64002 - Add send message buffering&lt;br /&gt;
* MDL-66226 - Show plain text in Messages summary pane&lt;br /&gt;
* MDL-61649 - Several core emails provide only text format&lt;br /&gt;
* MDL-35773 - Include files option in backup settings&lt;br /&gt;
* MDL-63453 - VideoJS upgrade to 7.6.5 including HTTP Live Streaming (HLS) and Dynamic Adaptive Streaming over HTTP (MPEG-DASH) support&lt;br /&gt;
* MDL-56549 - Add support for FLAC files&lt;br /&gt;
* MDL-62836 - Make awarding badges groups/groupings compliant&lt;br /&gt;
* MDL-60916 - Global Search: Replace course search form with global search&lt;br /&gt;
* MDL-64438 - Display course category in course related block&lt;br /&gt;
* MDL-66326 - Global search: Delete from search index when courses are deleted&lt;br /&gt;
* MDL-65183 - block_timeline can cause JSON parse error on dashboard when activities are saved with newline characters&lt;br /&gt;
* MDL-66612 - Calendar course event icon is different from course icon&lt;br /&gt;
* MDL-66775 - Add new Mobile setting for forcing a minimum app version to access the site&lt;br /&gt;
* MDL-66375 - Option to disable the &amp;quot;Forgotten password&amp;quot; feature in the app&lt;br /&gt;
* MDL-66753 - The People block is no longer needed and should be removed from core&lt;br /&gt;
&lt;br /&gt;
===For administrators===&lt;br /&gt;
&lt;br /&gt;
* MDL-66034 - Log role changes in more detail&lt;br /&gt;
* MDL-66570 - Allow disabling of cron output when capturing logs&lt;br /&gt;
* MDL-61804 - Let the admin control if lists of courses should be pre-sorted by visibility or not&lt;br /&gt;
* MDL-66133 - Let the administrator configure which user filters are shown by default&lt;br /&gt;
* MDL-63643 - Add ability to search/filter users by Last IP Address&lt;br /&gt;
* MDL-66119 - Disable GUI plugin uninstalls (eg $CFG-&amp;gt;uninstallclionly similar to $CFG-&amp;gt;disableupdateautodeploy)&lt;br /&gt;
* MDL-65201 - Automated backup course ordering&lt;br /&gt;
* MDL-65404 - Add column for enrol start dates to Upload users CSV&lt;br /&gt;
* MDL-40669 - Upload users via text file should include the optional user field &#039;disable notifications&#039;&lt;br /&gt;
* MDL-66705 - Add an example csv file for bulk uploading of users&lt;br /&gt;
* MDL-59470 - Option to duplicate a user tour&lt;br /&gt;
* MDL-65622 - Add a new event when a grade item has been created&lt;br /&gt;
* MDL-65369 - Include changed course settings in course_updated event&lt;br /&gt;
* MDL-65492 - Cache admin UI: make it easy re-purge the cache you just purged&lt;br /&gt;
* MDL-63127 - Redis Cache: implement compression&lt;br /&gt;
* MDL-66428 - Allow Redis cache to use PHP extension Zstd&lt;br /&gt;
* MDL-46317 - Private files space setting should use MB not Bytes&lt;br /&gt;
* MDL-7339 - Change &#039;Open to Google&#039; setting to &#039;Open to search engines&#039;&lt;br /&gt;
* MDL-65208 - Add cli upgrade option to test if an upgrade is required&lt;br /&gt;
* MDL-58439 - Admin pages login as guest and then throw Access denied error (should prompt for login) require_admin()&lt;br /&gt;
&lt;br /&gt;
==For developers==&lt;br /&gt;
&lt;br /&gt;
* MDL-66675 - New &amp;lt;tt&amp;gt;$CFG-&amp;gt;behat_pause_on_fail&amp;lt;/tt&amp;gt; option added&lt;br /&gt;
* MDL-46267 - The &amp;lt;tt&amp;gt;$CFG-&amp;gt;httpswwwroot&amp;lt;/tt&amp;gt; was removed&lt;br /&gt;
* MDL-66335 - New steps to navigate straight to any plugin web page. Plugins must implement their own resolver between page types and URLs.&lt;br /&gt;
* MDL-65349 - Profiling included and excluded URLs now are matched from start. Some adjustments may be needed.&lt;br /&gt;
* MDL-66633 - Quiz: quiz attempt API should let you create an attempt for a different user&lt;br /&gt;
* MDL-66709 - Components other than activity modules should be able to backup and restore question attempt data&lt;br /&gt;
* MDL-66754 - Question engine: report methods should not require a list of slots&lt;br /&gt;
* MDL-62497 - Add a new transpilation tool for ES6&lt;br /&gt;
* MDL-50346 - Remove the restriction to forbid subdirectories in the templates directory&lt;br /&gt;
* MDL-66327 - $DB-&amp;gt;get_records uses a lot of Peak RAM (with Postgres)&lt;br /&gt;
* MDL-66173 - Add hooks to extend all forms with /login/&lt;br /&gt;
* MDL-66367 - Caching of templates should use a new templaterev variable&lt;br /&gt;
* MDL-66304 - Allow support for xsendfile in alternative_file_system_class independently of local files&lt;br /&gt;
* MDL-66166 - Improve the moodlebot user agent and expose a function for plugins to use&lt;br /&gt;
* MDL-65646 - Move dependencies and subplugins to JSON&lt;br /&gt;
* MDL-55751 - Remove the CSS chunker from Moodle&lt;br /&gt;
* MDL-65438 - Allow themes to alter the core css url&#039;s&lt;br /&gt;
* MDL-65747 - Removed unused Pear_Crypt_CHAP library&lt;br /&gt;
&lt;br /&gt;
===Web services additions and updates===&lt;br /&gt;
&lt;br /&gt;
* MDL-65794 - Make some web service calls idempotent over http GET&lt;br /&gt;
* MDL-67043 - Web service to enable H5P offline access in the Moodle app&lt;br /&gt;
* MDL-64254 - New Web Services for updating a forum post (or a discussion topic post)&lt;br /&gt;
* MDL-65017 - New web service to delete forum posts&lt;br /&gt;
* MDL-64588 - New web services for adding and deleting comments&lt;br /&gt;
* MDL-66376 - Enforce app security by using tokenpluginfile.php instead webservice/pluginfile.php&lt;br /&gt;
* MDL-65400 - Blocks Web Services (for course and dashboard) should return the block settings&lt;br /&gt;
&lt;br /&gt;
===Component API upgrades===&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/admin/upgrade.txt admin/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/analytics/upgrade.txt analytics/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/blocks/recentlyaccessedcourses/upgrade.txt blocks/recentlyaccessedcourses/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/blocks/starredcourses/upgrade.txt blocks/starredcourses/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/blocks/upgrade.txt blocks/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/cache/upgrade.txt cache/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/calendar/upgrade.txt calendar/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/comment/upgrade.txt comment/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/format/upgrade.txt course/format/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/upgrade.txt course/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/customfield/field/upgrade.txt customfield/field/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/enrol/ldap/upgrade.txt enrol/ldap/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/enrol/upgrade.txt enrol/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/mlbackend/php/upgrade.txt lib/mlbackend/php/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/mlbackend/python/upgrade.txt lib/mlbackend/python/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/upgrade.txt lib/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/media/upgrade.txt media/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/message/upgrade.txt message/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/assign/upgrade.txt mod/assign/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/book/upgrade.txt mod/book/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/feedback/upgrade.txt mod/feedback/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/forum/upgrade.txt mod/forum/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/glossary/upgrade.txt mod/glossary/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/lti/upgrade.txt mod/lti/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/quiz/report/upgrade.txt mod/quiz/report/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/upgrade.txt mod/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/wiki/upgrade.txt mod/wiki/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/workshop/upgrade.txt mod/workshop/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/question/type/upgrade.txt question/type/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/question/upgrade.txt question/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/search/upgrade.txt search/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/theme/upgrade.txt theme/upgrade.txt]&lt;br /&gt;
* [https://git.in.moodle.com/moodle/moodle/blob/master/webservice/upgrade.txt webservice/upgrade.txt]&lt;br /&gt;
&lt;br /&gt;
==See also==&lt;br /&gt;
*[[Moodle 3.7 release notes]]&lt;br /&gt;
 &lt;br /&gt;
[[Category:Release notes]]&lt;br /&gt;
[[Category:Moodle 3.8]]&lt;br /&gt;
 &lt;br /&gt;
[[fr:Notes de mise à jour de Moodle 3.8]]&lt;br /&gt;
[[es:Notas de Moodle 3.8]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Templates&amp;diff=56926</id>
		<title>Templates</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Templates&amp;diff=56926"/>
		<updated>2020-02-14T09:44:41Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* What if a template contains javascript? */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Moodle 2.9}}&lt;br /&gt;
&lt;br /&gt;
= Templates =&lt;br /&gt;
&lt;br /&gt;
== What is a template? ==&lt;br /&gt;
A template is an alternative to writing blocks of HTML directly in javascript / php by concatenating strings. The end result is the same, but templates have a number of advantages:&lt;br /&gt;
* It is easier to see the final result of the template because the code for a template is very close to what the final HTML will look like&lt;br /&gt;
* Because the templating language is intentionally limited, it is hard to introduce complex logic into a template. This makes it far easier for a theme designer to override a template, without breaking the logic&lt;br /&gt;
* Templates can be rendered from javascript. This allows ajax operations to re-render a portion of the page.&lt;br /&gt;
&lt;br /&gt;
== How do I write a template? ==&lt;br /&gt;
Templates are written in a language called &amp;quot;[http://mustache.github.io/mustache.5.html Mustache]&amp;quot;. Mustache is written as HTML with additional tags used to format the display of the data. Mustache tags are made of 2 opening and closing curly braces &amp;lt;code xml&amp;gt;{{tag}}&amp;lt;/code&amp;gt;. There are a few variations of these tags that behave differently.&lt;br /&gt;
* &amp;lt;code xml&amp;gt;{{raiden}}&amp;lt;/code&amp;gt; This is a simple variable substitution. The variable named &amp;quot;raiden&amp;quot; will be searched for in the current context (and any parent contexts) and when a value is found, the entire tag will be replaced by the variable (HTML escaped).&lt;br /&gt;
* &amp;lt;code xml&amp;gt;{{{galaga}}}&amp;lt;/code&amp;gt; This is an unescaped variable substitution. Instead of escaping the variable before replacing it in the template, the variable is included raw. This is useful when the variable contains a block of HTML (for example).&lt;br /&gt;
* &amp;lt;code xml&amp;gt;{{#lemmings}} jump off cliff {{/lemmings}}&amp;lt;/code&amp;gt; These are opening and closing section tags. If the lemmings variable exists and evaluates to &amp;quot;not false&amp;quot; value, the variable is pushed on the stack, the contents of the section are parsed and included in the result. If the variable does not exist, or evaluates to false - the section will be skipped. If the variable lemmings evaluates to an array, the section will be repeated for each item in the array with the items of the array on the context. This is how to output a list.&lt;br /&gt;
* &amp;lt;code xml&amp;gt;{{^lemmings}} enjoy view {{/lemmings}}&amp;lt;/code&amp;gt; Equivalent of &amp;quot;if-not&amp;quot; block, there is no &amp;quot;else&amp;quot; in mustache.&lt;br /&gt;
* &amp;lt;code xml&amp;gt;{{&amp;gt; franken_style/name_of_template }}&amp;lt;/code&amp;gt; This is a partial. Think of it like an include. Templates can include other templates using this tag. In the called template, the data it sees (for including values is the same as the data available where the partial is included.&lt;br /&gt;
* &amp;lt;code xml&amp;gt;{{$blockvar}} ... {{/blockvar}}&amp;lt;/code&amp;gt; This is a block variable. It defines a section of the template that can be overridden when it&#039;s included in another template.&lt;br /&gt;
* &amp;lt;code xml&amp;gt;{{&amp;lt; template_name}} ... {{/template_name}}&amp;lt;/code&amp;gt; This is similar to including a partial but specifically indicates that you&#039;d like to override one or more block variables defined within the template you&#039;re including. You can override the block variables by defining a block variable within these tags that matches the name of the block variable you&#039;d like to override in the included template.&lt;br /&gt;
&lt;br /&gt;
So - putting this all together:&lt;br /&gt;
&lt;br /&gt;
recipe.mustache&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
&amp;lt;h3&amp;gt;{{recipename}}&amp;lt;/h3&amp;gt;&lt;br /&gt;
&amp;lt;p&amp;gt;{{description}}&amp;lt;/p&amp;gt;&lt;br /&gt;
&amp;lt;h4&amp;gt;Ingredients&amp;lt;/h4&amp;gt;&lt;br /&gt;
&amp;lt;ol&amp;gt;&lt;br /&gt;
{{#ingredients}}&lt;br /&gt;
&amp;lt;li&amp;gt;{{.}}&amp;lt;/li&amp;gt;&lt;br /&gt;
{{/ingredients}}&lt;br /&gt;
&amp;lt;/ol&amp;gt;&lt;br /&gt;
&amp;lt;h4&amp;gt;Steps&amp;lt;/h4&amp;gt;&lt;br /&gt;
&amp;lt;ol&amp;gt;&lt;br /&gt;
{{#steps}}&lt;br /&gt;
&amp;lt;li&amp;gt;{{{.}}}&amp;lt;/li&amp;gt;&lt;br /&gt;
{{/steps}}&lt;br /&gt;
&amp;lt;/ol&amp;gt;&lt;br /&gt;
{{ &amp;gt; ratethisrecipe }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
When given this data:&lt;br /&gt;
&amp;lt;code javascript&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
  recipename: &amp;quot;Cheese sandwich&amp;quot;,&lt;br /&gt;
  description: &amp;quot;Who doesn&#039;t like a good cheese sandwich?&amp;quot;,&lt;br /&gt;
  ingredients: [&amp;quot;bread&amp;quot;, &amp;quot;cheese&amp;quot;, &amp;quot;butter&amp;quot;],&lt;br /&gt;
  steps: [&amp;quot;&amp;lt;p&amp;gt;Step 1 is to spread the butter on the bread&amp;lt;/p&amp;gt;&amp;quot;, &amp;quot;&amp;lt;p&amp;gt;Step 2 is to put the cheese &amp;amp;quot;in&amp;amp;quot; the bread (not on top, or underneath)&amp;lt;/p&amp;gt;&amp;quot;]&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Gives this: &amp;lt;span style=&amp;quot;font-size:4em&amp;quot;&amp;gt;😋&amp;lt;/span&amp;gt;&lt;br /&gt;
&lt;br /&gt;
More info - there are much clearer explanations of templates on the [http://mustache.github.io/mustache.5.html Mustache] website. Try reading those pages &amp;quot;before&amp;quot; posting on stack overflow :) .&lt;br /&gt;
&lt;br /&gt;
=== Blocks (Moodle 3.0 onwards) ===&lt;br /&gt;
Blocks are a feature of Mustache that deserves a special mention. They are used as a form of inheritance - and are crucial to building a library of re-usable templates. To make use of &amp;quot;blocks&amp;quot; you define a parent template with replaceable sections. Each of those sections is marked with a &amp;quot;blocks&amp;quot; tag like this (A blocks tag looks like a regular tag, but the variable name is preceded with $):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
&amp;lt;section&amp;gt;&lt;br /&gt;
&amp;lt;h1&amp;gt;{{$sectionheading}}Default heading{{/sectionheading}}&amp;lt;/h1&amp;gt;&lt;br /&gt;
&amp;lt;div&amp;gt;&lt;br /&gt;
{{$content}}Content for section{{/content}}&lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
&amp;lt;/section&amp;gt;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now - wherever I need to re-use this template I can include it and replace the content of those sections at the same time. &lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{&amp;lt; section}}&lt;br /&gt;
{{$sectionheading}}Latest News{{/sectionheading}}&lt;br /&gt;
{{$content}}Nothing happened today - sorry!{{/content}}&lt;br /&gt;
{{/section}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Notice that when I include a template and I want to make use of blocks - the include tag points the other way:&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{&amp;lt; section}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Not&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{&amp;gt; section}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Blocks support looping and many other cool things - for more info see https://github.com/bobthecow/mustache.php/wiki/BLOCKS-pragma&lt;br /&gt;
&lt;br /&gt;
== Where do I put my templates? ==&lt;br /&gt;
&lt;br /&gt;
Templates go in the &amp;lt;componentdir&amp;gt;/templates folder and must have a .mustache file extension. When loading templates the template name is &amp;lt;componentname&amp;gt;/&amp;lt;filename&amp;gt; (no file extension). &lt;br /&gt;
&lt;br /&gt;
So &amp;quot;mod_lesson/timer&amp;quot; would load the template at mod/lesson/templates/timer.mustache.&lt;br /&gt;
&lt;br /&gt;
Note: Do not try and put your templates in sub folders under the &amp;quot;/templates&amp;quot; directory. This is not supported and will not work.&lt;br /&gt;
&lt;br /&gt;
== How do I call a template from javascript? ==&lt;br /&gt;
&lt;br /&gt;
Rendering a template from javascript is fairly easy. There is a new AMD module that can load/cache and render a template for you. &lt;br /&gt;
&lt;br /&gt;
&amp;lt;code javascript&amp;gt;&lt;br /&gt;
// This is AMD code for loading the &amp;quot;core/templates&amp;quot; module. see [Javascript Modules].&lt;br /&gt;
require([&#039;core/templates&#039;], function(templates) {&lt;br /&gt;
&lt;br /&gt;
    // This will be the context for our template. So {{name}} in the template will resolve to &amp;quot;Tweety bird&amp;quot;.&lt;br /&gt;
    var context = { name: &#039;Tweety bird&#039;, intelligence: 2 };&lt;br /&gt;
&lt;br /&gt;
    // This will call the function to load and render our template. &lt;br /&gt;
    templates.render(&#039;block_looneytunes/profile&#039;, context)&lt;br /&gt;
&lt;br /&gt;
    // It returns a promise that needs to be resoved.&lt;br /&gt;
            .then(function(html, js) {&lt;br /&gt;
                // Here eventually I have my compiled template, and any javascript that it generated.&lt;br /&gt;
                // The templates object has append, prepend and replace functions.&lt;br /&gt;
                templates.appendNodeContents(&#039;.block_looneytunes .content&#039;, html, js);&lt;br /&gt;
            }).fail(function(ex) {&lt;br /&gt;
                // Deal with this exception (I recommend core/notify exception function for this).&lt;br /&gt;
            });&lt;br /&gt;
});&lt;br /&gt;
&amp;lt;/code&amp;gt; &lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Under the hood, this did many clever things for us. It loaded the template via an ajax call if it was not cached. It found any missing lang strings in the template and loaded them in a single ajax request, it split the JS from the HTML and returned us both in easy to use way. Read on for how to nicely deal with the javascript parameter.&lt;br /&gt;
&lt;br /&gt;
Note: with some nice chaining and sugar, we can shorten the above example quite a bit:&lt;br /&gt;
&amp;lt;code javascript&amp;gt;&lt;br /&gt;
require([&#039;core/templates&#039;, &#039;core/notification&#039;], function(templates, notification) {&lt;br /&gt;
    var context = { name: &#039;Tweety bird&#039;, intelligence: 2 };&lt;br /&gt;
    templates.render(&#039;block_looneytunes/profile&#039;, context)&lt;br /&gt;
        .then(doneCallback)&lt;br /&gt;
        .fail(notification.exception);&lt;br /&gt;
});&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== What if a template contains javascript? ==&lt;br /&gt;
&lt;br /&gt;
Sometimes a template requires that some JS be run when it is added to the page in order to give it more features. In the template we can include blocks of javascript, but we should use a special section tag that has a &amp;quot;helper&amp;quot; method registered to handle javascript carefully. &lt;br /&gt;
&lt;br /&gt;
Example&lt;br /&gt;
[https://github.com/moodle/moodle/blob/master/lib/form/templates/element-advcheckbox-inline.mustache#L34 lib/form/templates/element-advcheckbox-inline.mustache]&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
&amp;lt;!-- HTML here --&amp;gt;&amp;gt;&lt;br /&gt;
{{^element.frozen}}&lt;br /&gt;
{{#js}}&lt;br /&gt;
require([&#039;theme_boost/form-display-errors&#039;], function(module) {&lt;br /&gt;
    module.enhance({{#quote}}{{element.id}}{{/quote}});&lt;br /&gt;
});&lt;br /&gt;
{{/js}}&lt;br /&gt;
{{/element.frozen}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If this template is rendered by PHP, the javascript is separated from the HTML, and is appended to a special section in the footer of the page &amp;quot;after&amp;quot; requirejs has loaded. This provides the optimal page loading speed. If the template is rendered by javascript, the javascript source will be passed to the &amp;quot;done&amp;quot; handler from the promise. Then, when the &amp;quot;done&amp;quot; handler has added the template to the DOM, it can call &lt;br /&gt;
&amp;lt;code javascript&amp;gt;templates.runTemplateJS(javascript);&amp;lt;/code&amp;gt; &lt;br /&gt;
which will run the javascript (by creating a new script tag and appending it to the page head).&lt;br /&gt;
&lt;br /&gt;
== What other helpers can I use? ==&lt;br /&gt;
&lt;br /&gt;
The implementation of these helpers is in classes like [https://github.com/moodle/moodle/blob/master/lib/classes/output/mustache_string_helper.php#L31 \core\output\mustache_string_helper]. This is set up in the [https://github.com/moodle/moodle/blob/master/lib/outputrenderers.php#L100 get_mustache method in renderer_base] (There should be no need to look at the implementation, unless you are interested.) If you are considering adding a new helper, it should be limited to display logic - and you need to be able to create identical helpers for the javascript and php implementations (javascript ones go in lib/amd/src/templates.js). &lt;br /&gt;
&lt;br /&gt;
=== {{# str }} ===&lt;br /&gt;
&lt;br /&gt;
There is a string helper for loading language strings.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{# str }} helloworld, mod_greeting {{/ str }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The first 2 parameters are the string id and the component name. So this is effectively Mustache variant of &amp;lt;code&amp;gt;get_string(&#039;helloworld&#039;, &#039;mod_greeting&#039;)&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
The optional third parameter defines the value for the string&#039;s &amp;lt;code&amp;gt;$a&amp;lt;/code&amp;gt; placeholder:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{# str }} iscool, mod_cool, David Beckham {{/ str }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This example would effectively do what &amp;lt;code&amp;gt;get_string(&#039;iscool&#039;, &#039;mod_cool&#039;, &#039;David Beckham&#039;)&amp;lt;/code&amp;gt; does in Moodle PHP code.&lt;br /&gt;
&lt;br /&gt;
Variable tags are allowed to define the value of the &amp;lt;code&amp;gt;$a&amp;lt;/code&amp;gt; placeholder:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{# str }} iscool, mod_cool, {{ name }} {{/ str }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
For strings that accept complex placeholder, see the following section.&lt;br /&gt;
&lt;br /&gt;
=== {{# quote }} ===&lt;br /&gt;
&lt;br /&gt;
As shown in the previous section, the &amp;lt;code&amp;gt;{{# str }}&amp;lt;/code&amp;gt; helper may need complex data structures passed as the value of the &amp;lt;code&amp;gt;$a&amp;lt;/code&amp;gt; placeholder. You can use a JSON object syntax in that case:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{# str }} iscool, mod_cool, { &amp;quot;firstname&amp;quot;: &amp;quot;David&amp;quot;, &amp;quot;lastname&amp;quot;: &amp;quot;Beckham&amp;quot; } {{/ str }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you wanted to use the context values instead of literal strings, you might intuitively use something like this:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{! DO NOT DO THIS !}}&lt;br /&gt;
{{# str }} iscool, mod_cool, { &amp;quot;firstname&amp;quot;: &amp;quot;{{ firstname }}&amp;quot;, &amp;quot;lastname&amp;quot;: &amp;quot;{{ lastname }}&amp;quot; } {{/ str }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
There is a potential problem though. If the variable tag &amp;lt;code&amp;gt;{{ firstname }}&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;{{ lastname }}&amp;lt;/code&amp;gt; evaluates to a string containing the double quote character, that will break the JSON syntax. We need to escape the double quotes potentially appearing in the variable tags. For this, use the &amp;lt;code&amp;gt;{{# quote }}&amp;lt;/code&amp;gt; helper:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{! This is OK !}}&lt;br /&gt;
{{# str }} iscool, mod_cool, { &amp;quot;firstname&amp;quot;:  {{# quote }}{{ firstname }}{{/ quote }}, &amp;quot;lastname&amp;quot;: {{# quote }}{{ lastname }}{{/ quote }} } {{/ str }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
See MDL-52136 for details.&lt;br /&gt;
=== {{# pix }} ===&lt;br /&gt;
&lt;br /&gt;
There is a pix icon helper for generating pix icon tags.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{# pix }} t/edit, core, Edit David Beckham {{/ pix }}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The first 2 parameters are the string id and the component name, the rest is the alt text for the image.&lt;br /&gt;
&lt;br /&gt;
=== {{# userdate }} (Moodle 3.3 onwards) ===&lt;br /&gt;
{{Moodle 3.3}}&lt;br /&gt;
This mustache template helper will format unix timestamps into a given human readable date format while using the user&#039;s timezone settings configured (if any) in Moodle. The helper will accept hardcoded values, context variables, or other helpers. &lt;br /&gt;
&lt;br /&gt;
The recommended way to use this helper is to use the string helper to get one of the core Moodle formats because they have been translated into other languages so you&#039;ll get multi-lang support for free (that&#039;s a pretty good deal!).&lt;br /&gt;
&lt;br /&gt;
==== Using the string helper (recommended) ====&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
// Assuming we had a context variable named &amp;quot;time&amp;quot; set to 1293876000.&lt;br /&gt;
{{#userdate}} {{time}}, {{#str}} strftimedate {{/str}} {{/userdate}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
This will ask the Moodle server for the string &amp;quot;strftimedate&amp;quot; and will use the value (which in this case is &amp;quot;%d %B %Y&amp;quot;)  to format the user date. So the resulting formatted timestamp from the userdate helper will be &amp;quot;01 January 2011&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
==== Using context variables ====&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
// Assuming we had a context variable named &amp;quot;time&amp;quot; set to 1293876000.&lt;br /&gt;
{{#userdate}} {{time}}, %A, %d %B %Y, %I:%M %p {{/userdate}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Will produce &amp;quot;Saturday, 01 January 2011, 10:00 AM&amp;quot;&lt;br /&gt;
&lt;br /&gt;
==== Using hardcoded values ====&lt;br /&gt;
&amp;lt;code xml&amp;gt;&lt;br /&gt;
{{#userdate}} 1293876000, %A, %d %B %Y, %I:%M %p {{/userdate}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Will produce &amp;quot;Saturday, 01 January 2011, 10:00 AM&amp;quot;&lt;br /&gt;
&lt;br /&gt;
=== {{# shortentext }} (Moodle 3.3 onwards) ===&lt;br /&gt;
{{Moodle 3.3}}&lt;br /&gt;
This helper can be used to shorten a large amount of text to a specified length and will append a trailing ellipsis to signify that the text has been shortened. &lt;br /&gt;
&lt;br /&gt;
The algorithm will attempt to preserve words while shortening to text. Words, for the purposes of the helper, are considered to be groups of consecutive characters broken by a space or, in the case of a multi-byte character, after the completion of the multi-byte character (rather than in the middle of the character).&lt;br /&gt;
&lt;br /&gt;
It will also attempt to preserve HTML in the text by keeping the opening and closing tags. Only text within the tags will be considered when calculating how much should be truncated to reach the desired length.&lt;br /&gt;
&lt;br /&gt;
The helper takes two comma separated arguments. The first is the desired length and the second is the text to be shortened. Both can be provided as context variables.&lt;br /&gt;
&lt;br /&gt;
==== Plain text ====&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
{{#shortentext}} 30, long text without any tags blah de blah blah blah what {{/shortentext}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Will produce:&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
long text without any tags ...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== HTML text ====&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
{{#shortentext}} 30, &amp;lt;div class=&#039;frog&#039;&amp;gt;&amp;lt;p&amp;gt;&amp;lt;blockquote&amp;gt;Long text with tags that will be chopped off but &amp;lt;b&amp;gt;should be added back again&amp;lt;/b&amp;gt;&amp;lt;/blockquote&amp;gt;&amp;lt;/p&amp;gt;&amp;lt;/div&amp;gt;&amp;lt;/p&amp;gt; {{/shortentext}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Will produce:&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
&amp;lt;div class=&#039;frog&#039;&amp;gt;&amp;lt;p&amp;gt;&amp;lt;blockquote&amp;gt;Long text with tags that ...&amp;lt;/blockquote&amp;gt;&amp;lt;/p&amp;gt;&amp;lt;/div&amp;gt;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Multi-byte text ====&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
{{#shortentext}} 6, 𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟 {{/shortentext}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Will produce:&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
𠮟𠮟𠮟...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== How do I call a template from php? ==&lt;br /&gt;
&lt;br /&gt;
The templates in php are attached to the renderers. There is a renderer method &amp;quot;render_from_template($templatename, $context)&amp;quot; that does the trick.&lt;br /&gt;
&lt;br /&gt;
Note $context is nothing to do with normal Moodle &#039;contexts&#039;. It is the data passed to the template (the &#039;context&#039; mentioned in mustache documentation).&lt;br /&gt;
&lt;br /&gt;
== How do templates work with renderers? ==&lt;br /&gt;
&lt;br /&gt;
Extra care must be taken to ensure that the data passed to the context parameter is useful to the templating language. The template language cannot:&lt;br /&gt;
* Call functions&lt;br /&gt;
* Perform any boolean logic&lt;br /&gt;
* Render renderables&lt;br /&gt;
* Do capability checks&lt;br /&gt;
* Make DB queries&lt;br /&gt;
&lt;br /&gt;
So - I have &amp;quot;some&amp;quot; data in my renderable and some logic and HTML generation in my render method for that renderable - how do I refactor this to use a template?&lt;br /&gt;
&lt;br /&gt;
The first thing to note, is that you don&#039;t have to use a template if you don&#039;t want to. It just means that themers will still have to override your render method, instead of just overriding the template. But if you DO want to use a template, you will earn &amp;quot;cred&amp;quot; with themers, and you will be able to re-render parts of your interface from javascript in response to ajax requests without reloading the whole page (that&#039;s cool).&lt;br /&gt;
&lt;br /&gt;
There is a simple pattern to use to hook a template into a render method. If you make your renderable implement templatable as well as renderable - it will have to implement a new method &amp;quot;export_for_template(renderer_base $output)&amp;quot;. This method takes the data stored in the renderable and &amp;quot;flattens it&amp;quot; so it can be used in a template. If there is some nested data in the renderable (like other renderables) and they do not support templates, they can be &amp;quot;rendered&amp;quot; into the flat data structure using the renderer parameter. It should return an stdClass with properties that are only made of simple types: int, string, bool, float, stdClass or arrays of these types. Then the render method can updated to export the data and render it with the template.&lt;br /&gt;
&lt;br /&gt;
In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity.  Passing your widget directly to $OUTPUT-&amp;gt;renderer() will infer the name of your template, call export_for_template() and render_from_template(), then return the result.&lt;br /&gt;
&lt;br /&gt;
In the renderable:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
 * Export this data so it can be used as the context for a mustache template.&lt;br /&gt;
 *&lt;br /&gt;
 * @return stdClass&lt;br /&gt;
 */&lt;br /&gt;
public function export_for_template(renderer_base $output) {&lt;br /&gt;
&lt;br /&gt;
    $data = new stdClass();&lt;br /&gt;
    $data-&amp;gt;canmanage = $this-&amp;gt;canmanage;&lt;br /&gt;
    $data-&amp;gt;things = array();&lt;br /&gt;
    foreach ($this-&amp;gt;things as $thing) {&lt;br /&gt;
        $data-&amp;gt;things[] = $thing-&amp;gt;to_record();&lt;br /&gt;
    }&lt;br /&gt;
    $data-&amp;gt;navigation = array();&lt;br /&gt;
    foreach ($this-&amp;gt;navigation as $button) {&lt;br /&gt;
        $data-&amp;gt;navigation[] = $output-&amp;gt;render($button);&lt;br /&gt;
    }&lt;br /&gt;
&lt;br /&gt;
    return $data;&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In your component&#039;s renderer:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
 * Render via a template.&lt;br /&gt;
 *&lt;br /&gt;
 * @param mywidget $widget&lt;br /&gt;
 *&lt;br /&gt;
 * @return string HTML for the page&lt;br /&gt;
 */&lt;br /&gt;
protected function render_mywidget(mywidget $widget) {&lt;br /&gt;
    $data = $widget-&amp;gt;export_for_template($this);&lt;br /&gt;
    // Do other logic if needed.&lt;br /&gt;
    return $this-&amp;gt;render_from_template(&#039;tool_myplugin/mywidget&#039;, $data);&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In your page:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$output = $PAGE-&amp;gt;get_renderer(&#039;tool_myplugin&#039;);&lt;br /&gt;
echo $output-&amp;gt;render($widget);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== How to I override a template in my theme? ==&lt;br /&gt;
&lt;br /&gt;
Templates can be overridden a bit easier than overriding a renderer. First - find the template that you want to change. E.g. &amp;quot;mod/wiki/templates/ratingui.mustache&amp;quot;. Now, create a sub-folder under your themes &amp;quot;templates&amp;quot; directory with the component name of the plugin you are overriding. E.g &amp;quot;theme/timtam/templates/mod_wiki&amp;quot;. Finally, copy the ratingui.mustache file into the newly created &amp;quot;theme/timtam/templates/mod_wiki&amp;quot; and edit it. You should see your changes immediately if theme designer mode is on. Note: templates are cached just like CSS, so if you are not using theme designer mode you will need to purge all caches to see the latest version of an edited template. If the template you are overriding contains a documentation comment (see next section) it is recommended to remove it, it will still show the documentation in the template library.&lt;br /&gt;
&lt;br /&gt;
== Should I document my templates? ==&lt;br /&gt;
&lt;br /&gt;
Yes!!!! Theme designers need to know the limits of what they can expect to change without breaking anything. As a further benefit - your beautiful new template can be displayed in the &amp;quot;Template Library&amp;quot; tool shipped with Moodle. In order to provide nice documentation and examples for the Template Library, you should follow these conventions when documenting your template.&lt;br /&gt;
&lt;br /&gt;
=== Add a documentation comment to your template ===&lt;br /&gt;
Mustache comments look like this:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
  {{! &lt;br /&gt;
   I am a comment.&lt;br /&gt;
   I can span multiple lines.&lt;br /&gt;
  }}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The template library will look for a mustache comment that contains this special marker as the documentation to display, and the source of an example context.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
@template component/templatename&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Useful things to include in the documentation for a template ====&lt;br /&gt;
===== Classes required for JS =====&lt;br /&gt;
This is a list of classes that are used by the javascript for this template. If removing a class from an element in the template will break the javascript, list it here.&lt;br /&gt;
&lt;br /&gt;
===== Data attributes required for JS =====&lt;br /&gt;
This is a list of data attributes (e.g. data-enhance=&amp;quot;true&amp;quot;) that are used by the javascript for this template. If removing a data attribute from an element in the template will break the javascript, list it here.&lt;br /&gt;
&lt;br /&gt;
===== Context variables required for this template =====&lt;br /&gt;
This is a description of the data that may be contained in the context that is passed to the template. Be explicit and document every attribute.&lt;br /&gt;
&lt;br /&gt;
===== Example context (JSON) =====&lt;br /&gt;
The Template Library will look for this data in your documentation comment as it allows it to render a &amp;quot;preview&amp;quot; of the template right in the Template Library. This is useful for theme designers to test all the available templates in their new theme to make sure they look nice in a new theme. It is also useful to make sure the template responds to different screen sizes, languages and devices. The format is a JSON-encoded object that is passed directly into the render method for this template. &lt;br /&gt;
&lt;br /&gt;
==== A full example ====&lt;br /&gt;
lib/templates/pix_icon.mustache&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
  {{!                                                                                                                                 &lt;br /&gt;
    This file is part of Moodle - http://moodle.org/                                                                                &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    Moodle is free software: you can redistribute it and/or modify                                                                  &lt;br /&gt;
    it under the terms of the GNU General Public License as published by                                                            &lt;br /&gt;
    the Free Software Foundation, either version 3 of the License, or                                                               &lt;br /&gt;
    (at your option) any later version.                                                                                             &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    Moodle is distributed in the hope that it will be useful,                                                                       &lt;br /&gt;
    but WITHOUT ANY WARRANTY; without even the implied warranty of                                                                  &lt;br /&gt;
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                                                                   &lt;br /&gt;
    GNU General Public License for more details.                                                                                    &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    You should have received a copy of the GNU General Public License                                                               &lt;br /&gt;
    along with Moodle.  If not, see &amp;lt;http://www.gnu.org/licenses/&amp;gt;.                                                                 &lt;br /&gt;
  }}                                                                                                                                  &lt;br /&gt;
  {{!                                                                                                                                 &lt;br /&gt;
    @template core/pix_icon                                                                                                         &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    Moodle pix_icon template.                                                                                                       &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    The purpose of this template is to render a pix_icon.                                                                           &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    Classes required for JS:                                                                                                        &lt;br /&gt;
    * none                                                                                                                          &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    Data attributes required for JS:                                                                                                &lt;br /&gt;
    * none                                                                                                                          &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    Context variables required for this template:                                                                                   &lt;br /&gt;
    * attributes Array of name / value pairs.                                                                                       &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
    Example context (json):                                                                                                         &lt;br /&gt;
    {                                                                                                                               &lt;br /&gt;
        &amp;quot;attributes&amp;quot;: [                                                                                                             &lt;br /&gt;
            { &amp;quot;name&amp;quot;: &amp;quot;src&amp;quot;, &amp;quot;value&amp;quot;: &amp;quot;http://moodle.com/wp-content/themes/moodle/images/logo-hat2.png&amp;quot; },                          &lt;br /&gt;
            { &amp;quot;name&amp;quot;: &amp;quot;class&amp;quot;, &amp;quot;value&amp;quot;: &amp;quot;iconsmall&amp;quot; }                                                                               &lt;br /&gt;
        ]                                                                                                                           &lt;br /&gt;
    }                                                                                                                               &lt;br /&gt;
                                                                                                                                    &lt;br /&gt;
  }}                                                                                                                                  &lt;br /&gt;
  &amp;lt;img {{#attributes}}{{name}}=&amp;quot;{{value}}&amp;quot; {{/attributes}}/&amp;gt;&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Coding style for templates ==&lt;br /&gt;
This section documents some coding style guidelines to follow when writing templates. The reason for these guidelines is to promote consistency, and interoperability of the templates.&lt;br /&gt;
&lt;br /&gt;
=== Include GPL at the top of each template ===&lt;br /&gt;
&lt;br /&gt;
Templates are a form of code and it is appropriate to license them like any other code.&lt;br /&gt;
&lt;br /&gt;
===Include a documentation comment for each template===&lt;br /&gt;
&lt;br /&gt;
The exception is when you are overriding a template, if the documentation from the parent still applies, you do not need to copy it to the overridden template.&lt;br /&gt;
&lt;br /&gt;
===Use data-attributes for JS hooks===&lt;br /&gt;
&lt;br /&gt;
Data attributes are ideal for adding javascript hooks to templates because:&lt;br /&gt;
* Classes are meant for styling - theme designers should be able to change the classes at will without breaking any functionality.&lt;br /&gt;
* IDs must be unique in the page, but it is not possible to control how many times the same template might be included in the page.&lt;br /&gt;
* Data attributes can have meaningful names and can be efficiently queried with a selector&lt;br /&gt;
&lt;br /&gt;
===Avoid custom CSS for templates===&lt;br /&gt;
&lt;br /&gt;
This is not a hard rule, but a preference. We already have too much CSS in Moodle - where ever possible we should try and re-use the existing CSS instead of adding new CSS to support every new template.&lt;br /&gt;
&lt;br /&gt;
===Re-use core templates as much as possible===&lt;br /&gt;
&lt;br /&gt;
First we need to build the core set of reusable templates - but once that is in place we should always try to re-use those core templates to build interfaces. This will make Moodle more consistent, attractive and customisable.&lt;br /&gt;
&lt;br /&gt;
===Do use the CSS framework classes directly in the templates===&lt;br /&gt;
&lt;br /&gt;
We have bootstrap in core - so lets make the most of it. There is no problem using bootstrap classes in core templates, as long as the &amp;quot;base&amp;quot; theme is also tested, and an overridden template is added there if required.&lt;br /&gt;
&lt;br /&gt;
===Avoid IDs for styling or javascript===&lt;br /&gt;
&lt;br /&gt;
IDs should never evet be used for styling as they have a high CSS specificity, and so are hard to override. In addition, IDs should be unique in the page, which implies that a template could only be used once in a page. IDs are also not ideal for javascript, for the same reason (must be unique in a page).&lt;br /&gt;
&lt;br /&gt;
The only acceptable case to use an ID is you need to create a one to one connection between the JS and template. In this case use the uniqid helper to generate an ID that will not conflict with any other template on the page, and use it as part of the ID.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
&amp;lt;div id=&amp;quot;{{uniqid}}-somethingspecific&amp;quot;&amp;gt;&lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
{{#js}}&lt;br /&gt;
    callFunction(&#039;{{uniqid}}-somethingspecific&#039;);&lt;br /&gt;
{{/js}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===Follow CSS coding style===&lt;br /&gt;
&lt;br /&gt;
https://docs.moodle.org/dev/CSS_coding_style&lt;br /&gt;
&lt;br /&gt;
Use hyphens as word-separators for class names. &lt;br /&gt;
Use lower case class names.&lt;br /&gt;
&lt;br /&gt;
===Wrap each template in one node with a classname that matches the template name===&lt;br /&gt;
&lt;br /&gt;
Generate a class name by combining the component and template names and separating words with underscore.&lt;br /&gt;
&lt;br /&gt;
e.g.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
&amp;lt;div class=&amp;quot;core_user_header&amp;quot;&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
[[Category:AJAX]]&lt;br /&gt;
[[Category:Javascript]]&lt;br /&gt;
[[Category:Output]]&lt;br /&gt;
&lt;br /&gt;
===Iterating over php arrays in a mustache template===&lt;br /&gt;
&lt;br /&gt;
Mustache treats hashes and arrays differently because of cross language compatibility&lt;br /&gt;
In php arrays and hashes are the same, but mustache treats them differently&lt;br /&gt;
It decides a php array is a hash and will not iterate over it if it is non 0 indexed and/or has a gap in the key numbers&lt;br /&gt;
so in short&lt;br /&gt;
you need to&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$datafortemplate-&amp;gt;mylist =  array_values($myarraywithnonnumerickeys)&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
you could also use &lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$datafortemplate-&amp;gt;mylist = new ArrayIterator($myarraywithnonnumerickeys);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
BUT this fails when $myarraywithnonnumerickeys is empty and you try to use&lt;br /&gt;
&amp;lt;code html5&amp;gt;&lt;br /&gt;
{{#mylist}}&lt;br /&gt;
with an array iterator if mylist is empty this block will not run&lt;br /&gt;
{{/mylist}}&lt;br /&gt;
{{^mylist}}&lt;br /&gt;
with an array iterator mylist will not run this block either because it is not quite empty&lt;br /&gt;
{{/mylist}}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===Test for not empty array in a mustache template===&lt;br /&gt;
&lt;br /&gt;
Short answer you can&#039;t. Include a specific property in the context like &amp;quot;hasusers&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
In php &lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{{#users.0}} blah {{/users.0}}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
will work but please don&#039;t use this syntax, it will break if the template is used in javascript AND it mucks up the context.&lt;br /&gt;
&lt;br /&gt;
In javascript&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{{#users.length}} blah {{/users.length}}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
will work but please don&#039;t use this syntax, it will break if the template is used in php.&lt;br /&gt;
&lt;br /&gt;
===Squash whitespace in a template===&lt;br /&gt;
Sometimes whitespace is significant, for example inside a link it will show with an underline. If you want 2 mustache tags from separate lines to be rendered with no whitespace between them you can use mustache comments to squash the whitespace.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;a href=&amp;quot;blah&amp;quot;&amp;gt;{{!&lt;br /&gt;
}}{{icon}}{{!&lt;br /&gt;
}}{{name}}&amp;lt;/a&amp;gt;&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== How do I write core templates? ==&lt;br /&gt;
Core templates should ideally be simple generic components that can be used within other templates to create more complex page layouts. They should be flexible enough for developers and themers to easily use without having to replace the template. The templates should attempt to encapsulate some core structure for the element as well as key classes while allowing the content to be easily overridden. Ultimately we want to avoid having duplicate HTML copied from template to template where possible, particularly if the HTML element has some classes associated with it.&lt;br /&gt;
&lt;br /&gt;
Mustache relies on variables to substitute context data into the template but unfortunately it&#039;s very unlikely that the the names of the context data will match what the template is expecting for all the places that the template might be used. So in order to allow easy extensibility and avoid having to duplicate templates just to rename the variables we can wrap them in block variables which would allow the template that is including our template to replace that variable with one from it&#039;s own context inline.&lt;br /&gt;
&lt;br /&gt;
There are a few key points to keep in mind when writing a core template:&lt;br /&gt;
* Consider how your template will actually be used. Try writing a test page that uses your template to help discover some of the assumptions you might have in the template.&lt;br /&gt;
* The example context you provide in the template is mostly just for showing the template in the template library and is likely not how your template will actually be used. Most uses of the template will have a different context all together.&lt;br /&gt;
* Try to enforce a core structure but avoid enforcing a specific context. Content should be overridable.&lt;br /&gt;
* Use block variables to indicate sections of your template that people are likely to want to change. Typically where they will be wanting to substitute in their own content.&lt;br /&gt;
* Try to keep any javascript that accompanies the template as decoupled from the HTML / CSS structure of the template as possible. Instead of relying on the existence of certain HTML elements or CSS classes it is generally better to leverage data-attributes which can be added to any element.&lt;br /&gt;
&lt;br /&gt;
=== An example: tabs ===&lt;br /&gt;
Let&#039;s go through an example to illustrate how you might build a core template. For the example we&#039;ll be building a tabs template, since it&#039;s a fairly complex component that requires the use of block variables and javascript.&lt;br /&gt;
&lt;br /&gt;
First we can create a basic template to get the general structure down, let&#039;s call it tabs. Here&#039;s what it might look like:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;div id=&amp;quot;{{ uniqid }}-tab-container&amp;quot;&amp;gt;&lt;br /&gt;
    &amp;lt;ul role=&amp;quot;tablist&amp;quot; class=&amp;quot;nav nav-tabs&amp;quot;&amp;gt;&lt;br /&gt;
		{{# tabs }}&lt;br /&gt;
			&amp;lt;li role=&amp;quot;tab&amp;quot;&lt;br /&gt;
					data-target=&amp;quot;{{ uniqid }}-{{ id }}&amp;quot;&lt;br /&gt;
					data-selected-class=&amp;quot;active&amp;quot;&lt;br /&gt;
					aria-controls=&amp;quot;{{ uniqid }}-{{ id }}&amp;quot;&lt;br /&gt;
					aria-selected=&amp;quot;false&amp;quot; tabindex=&amp;quot;-1&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
				&amp;lt;a href=&amp;quot;#&amp;quot;&amp;gt;{{{ name }}}&amp;lt;/a&amp;gt;&lt;br /&gt;
			&amp;lt;/li&amp;gt;&lt;br /&gt;
		{{/ tabs }}&lt;br /&gt;
	&amp;lt;/ul&amp;gt;&lt;br /&gt;
    &amp;lt;div class=&amp;quot;tab-content&amp;quot;&amp;gt;&lt;br /&gt;
		{{# tabs }}&lt;br /&gt;
			&amp;lt;div role=&amp;quot;tabpanel&amp;quot;&lt;br /&gt;
				class=&amp;quot;tab-pane&amp;quot;&lt;br /&gt;
				id=&amp;quot;{{ uniqid }}-{{ id }}&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
				{{{ content }}}&lt;br /&gt;
			&amp;lt;/div&amp;gt;&lt;br /&gt;
		{{/ tabs }}&lt;br /&gt;
	&amp;lt;/div&amp;gt;&lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
{{#js}}&lt;br /&gt;
    require([&#039;jquery&#039;,&#039;core/tabs&#039;], function($, tabs) {&lt;br /&gt;
&lt;br /&gt;
        var container = $(&amp;quot;#{{ uniqid }}-tab-container&amp;quot;);&lt;br /&gt;
        tabs.create(container);&lt;br /&gt;
    });&lt;br /&gt;
{{/js}}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The template requires a context that looks something like:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
	&amp;quot;tabs&amp;quot;: [&lt;br /&gt;
		{&amp;quot;id&amp;quot;:&amp;quot;tab1&amp;quot;,&amp;quot;name&amp;quot;:&amp;quot;Tab 1&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;This is tab 1 content &amp;lt;a href=\&amp;quot;#\&amp;quot;&amp;gt;test&amp;lt;/a&amp;gt;&amp;quot;},&lt;br /&gt;
		{&amp;quot;id&amp;quot;:&amp;quot;tab2&amp;quot;,&amp;quot;name&amp;quot;:&amp;quot;Tab 2&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;This is tab 2 content &amp;lt;a href=\&amp;quot;#\&amp;quot;&amp;gt;test&amp;lt;/a&amp;gt;&amp;quot;},&lt;br /&gt;
		{&amp;quot;id&amp;quot;:&amp;quot;tab3&amp;quot;,&amp;quot;name&amp;quot;:&amp;quot;Tab 3&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;This is tab 3 content &amp;lt;a href=\&amp;quot;#\&amp;quot;&amp;gt;test&amp;lt;/a&amp;gt;&amp;quot;}&lt;br /&gt;
	]&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The javascript required to power the tabs element (keyboard navigation, show / hide panels etc) is written as an AMD module and is included by the template. The javascript is a little too large to go through here, but some key points to consider when writing it are:&lt;br /&gt;
It should ideally be independent of the HTML structure, so if someone wants to completely rewrite the tabs to be different elements (e.g. buttons or a set of divs) then the same javascript can be used without needing to change it. In order to achieve this it is important to identify the key components of the template.&lt;br /&gt;
&lt;br /&gt;
In this case it is a tab list, a tab and it&#039;s content. One way to identify these components would be to inspect the structure of the DOM, for example you might say &amp;quot;find me the ul element&amp;quot; when looking for the tab list and then &amp;quot;find my the child li elements&amp;quot; to find the tabs. While this would work, it couples your javascript to the HTML structure and makes it difficult to change later. A different approach would be to use the element attributes, for example you might say &amp;quot;find my the element with the role &#039;tablist&#039;&amp;quot; to get the tab list and then &amp;quot;find me the elements with the role &#039;tab&#039;&amp;quot; to get the tabs. This allows the HTML structure to change without breaking the javascript (as long as the correct attributes are set, of course).&lt;br /&gt;
&lt;br /&gt;
Another point of consideration for this example is what class to apply to a tab when it is selected. It makes sense to just apply something like &amp;quot;active&amp;quot; in the javascript, but that once again couples it to a particular CSS framework which makes it more difficult to change without modifying the javascript. In this case I chose to add a data attribute to the element to indicate which class will be set when the tab is selected. This means the javascript doesn&#039;t have to guess what the appropriate class is, it can just get it from the template.&lt;br /&gt;
&lt;br /&gt;
Ok, so we&#039;ve got our basic template. It&#039;s time to use it! Let&#039;s say we want to create a simple user profile page that might show 2 tabs, the first tab will be the user&#039;s name and the second tab will be the user&#039;s email address (please excuse the contrived example).&lt;br /&gt;
&lt;br /&gt;
Here&#039;s what the page might look like:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;html&amp;gt;&lt;br /&gt;
    &amp;lt;header&amp;gt;&amp;lt;title&amp;gt;User Profile&amp;lt;/title&amp;gt;&amp;lt;/header&amp;gt;&lt;br /&gt;
    &amp;lt;body&amp;gt;&lt;br /&gt;
        {{&amp;lt; core/tabs }}&lt;br /&gt;
    &amp;lt;/body&amp;gt;&lt;br /&gt;
&amp;lt;/html&amp;gt;&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
That looks pretty simple! The only problem is, how do I get my content there? I would have to supply a context like this in order to display the tabs I want:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
	&amp;quot;tabs&amp;quot;: [&lt;br /&gt;
		{&amp;quot;id&amp;quot;:&amp;quot;tab1&amp;quot;,&amp;quot;name&amp;quot;:&amp;quot;Name&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;Your name is Mr. Test User.&amp;quot;},&lt;br /&gt;
		{&amp;quot;id&amp;quot;:&amp;quot;tab2&amp;quot;,&amp;quot;name&amp;quot;:&amp;quot;Email&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;Your email is testuser@example.com&amp;quot;},&lt;br /&gt;
	]&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Let&#039;s assume that the context for this page doesn&#039;t match what the tabs template is expecting though (as will be the case most of the time). Let&#039;s assume the tabs template is being rendered with this context:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
	&amp;quot;name&amp;quot;:&amp;quot;Mr. Test User&amp;quot;,&lt;br /&gt;
	&amp;quot;email&amp;quot;:&amp;quot;testuser@example.com&amp;quot;&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Unfortunately, we&#039;ll almost certainly never have complete control over all of the contexts that our template will be rendered in which means we&#039;ll be expecting people to write new webservices to supply the same data in different formats every time they want to use a template. It becomes an unmanageable problem.&lt;br /&gt;
&lt;br /&gt;
Enter blocks! We can make the template more flexible by defining sections of the template that can be overriden when they are included. Pretty neat! This will allow us to enforce a certain core structure but not enforce a context on the template that is including the tabs.&lt;br /&gt;
&lt;br /&gt;
Let&#039;s have another go at that template, this time leveraging blocks:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;div id=&amp;quot;{{ uniqid }}-tab-container&amp;quot;&amp;gt;&lt;br /&gt;
	{{$ tabheader }}&lt;br /&gt;
		&amp;lt;ul role=&amp;quot;tablist&amp;quot; class=&amp;quot;nav nav-tabs&amp;quot;&amp;gt;&lt;br /&gt;
			{{$ tablist }}&lt;br /&gt;
				{{# tabs }}&lt;br /&gt;
					&amp;lt;li role=&amp;quot;tab&amp;quot;&lt;br /&gt;
							data-target=&amp;quot;{{ uniqid }}-{{ id }}&amp;quot;&lt;br /&gt;
							data-selected-class=&amp;quot;active&amp;quot;&lt;br /&gt;
							aria-controls=&amp;quot;{{ uniqid }}-{{ id }}&amp;quot;&lt;br /&gt;
							aria-selected=&amp;quot;false&amp;quot; tabindex=&amp;quot;-1&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
						&amp;lt;a href=&amp;quot;#&amp;quot;&amp;gt;{{{ name }}}&amp;lt;/a&amp;gt;&lt;br /&gt;
					&amp;lt;/li&amp;gt;&lt;br /&gt;
				{{/ tabs }}&lt;br /&gt;
			{{/ tablist }}&lt;br /&gt;
		&amp;lt;/ul&amp;gt;&lt;br /&gt;
	{{/ tabheader }}&lt;br /&gt;
	{{$ tabbody }}&lt;br /&gt;
		&amp;lt;div class=&amp;quot;tab-content&amp;quot;&amp;gt;&lt;br /&gt;
			{{$ tabcontent }}&lt;br /&gt;
				{{# tabs }}&lt;br /&gt;
					&amp;lt;div role=&amp;quot;tabpanel&amp;quot;&lt;br /&gt;
						class=&amp;quot;tab-pane&amp;quot;&lt;br /&gt;
						id=&amp;quot;{{ uniqid }}-{{ id }}&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
						{{{ content }}}&lt;br /&gt;
					&amp;lt;/div&amp;gt;&lt;br /&gt;
				{{/ tabs }}&lt;br /&gt;
			{{/ tabcontent }}&lt;br /&gt;
		&amp;lt;/div&amp;gt;&lt;br /&gt;
	{{/ tabbody }}&lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
{{#js}}&lt;br /&gt;
    require([&#039;jquery&#039;,&#039;core/tabs&#039;], function($, tabs) {&lt;br /&gt;
&lt;br /&gt;
        var container = $(&amp;quot;#{{ uniqid }}-tab-container&amp;quot;);&lt;br /&gt;
        tabs.create(container);&lt;br /&gt;
    });&lt;br /&gt;
{{/js}}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A summary of what we&#039;ve changed:&lt;br /&gt;
* Added a $tabheader block around the tab list, in case someone wants to change the ul element to something else.&lt;br /&gt;
* Added a $tablist block around the group of tabs to allow them to be overriden on incldue.&lt;br /&gt;
* Added a $tabbody block around the content, in case someone wants to change the content elements from divs.&lt;br /&gt;
* Added a $tabcontent block around the tab variable for the content to allow the content to be overriden on inlcude.&lt;br /&gt;
&lt;br /&gt;
Now let&#039;s see what using this template looks like for your User Profile page:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;html&amp;gt;&lt;br /&gt;
    &amp;lt;header&amp;gt;&amp;lt;title&amp;gt;User Profile&amp;lt;/title&amp;gt;&amp;lt;/header&amp;gt;&lt;br /&gt;
    &amp;lt;body&amp;gt;&lt;br /&gt;
        {{&amp;gt; core/tabs }}&lt;br /&gt;
			{{$ tablist }}&lt;br /&gt;
				&amp;lt;li role=&amp;quot;tab&amp;quot;&lt;br /&gt;
						data-target=&amp;quot;{{ uniqid }}-tab1&amp;quot;&lt;br /&gt;
						data-selected-class=&amp;quot;active&amp;quot;&lt;br /&gt;
						aria-controls=&amp;quot;{{ uniqid }}-tab1&amp;quot;&lt;br /&gt;
						aria-selected=&amp;quot;false&amp;quot; tabindex=&amp;quot;-1&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
					&amp;lt;a href=&amp;quot;#&amp;quot;&amp;gt;Name&amp;lt;/a&amp;gt;&lt;br /&gt;
				&amp;lt;/li&amp;gt;&lt;br /&gt;
				&amp;lt;li role=&amp;quot;tab&amp;quot;&lt;br /&gt;
						data-target=&amp;quot;{{ uniqid }}-tab2&amp;quot;&lt;br /&gt;
						data-selected-class=&amp;quot;active&amp;quot;&lt;br /&gt;
						aria-controls=&amp;quot;{{ uniqid }}-tab2&amp;quot;&lt;br /&gt;
						aria-selected=&amp;quot;false&amp;quot; tabindex=&amp;quot;-1&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
					&amp;lt;a href=&amp;quot;#&amp;quot;&amp;gt;Email&amp;lt;/a&amp;gt;&lt;br /&gt;
				&amp;lt;/li&amp;gt;&lt;br /&gt;
			{{/ tablist }}&lt;br /&gt;
			{{$ tabcontent }}&lt;br /&gt;
				&amp;lt;div role=&amp;quot;tabpanel&amp;quot;&lt;br /&gt;
					class=&amp;quot;tab-pane&amp;quot;&lt;br /&gt;
					id=&amp;quot;{{ uniqid }}-tab1&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
					Your name is {{ name }}.&lt;br /&gt;
				&amp;lt;/div&amp;gt;&lt;br /&gt;
				&amp;lt;div role=&amp;quot;tabpanel&amp;quot;&lt;br /&gt;
					class=&amp;quot;tab-pane&amp;quot;&lt;br /&gt;
					id=&amp;quot;{{ uniqid }}-tab2&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
					Your email address is {{ email }}.&lt;br /&gt;
				&amp;lt;/div&amp;gt;&lt;br /&gt;
			{{/ tabcontent }}&lt;br /&gt;
		{{/ core/tabs }}&lt;br /&gt;
    &amp;lt;/body&amp;gt;&lt;br /&gt;
&amp;lt;/html&amp;gt;&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
That looks a bit better! Now we&#039;ve been able to use the blocks to successfully change the template to use the context available to this page, we no longer need a &amp;quot;tabs&amp;quot; array with &amp;quot;name&amp;quot; and &amp;quot;content&amp;quot;. Even the javascript will continue to work because we&#039;ve kept the correct element attributes. &lt;br /&gt;
&lt;br /&gt;
We&#039;ve still got a slight problem though... In order to change the data for the template we&#039;ve had to copy &amp;amp; paste the HTML from the original template into our blocks as we do the override. While this works fine in this example, it means we don&#039;t quite get the encapsulation we want within the templates since we&#039;re leaking internal implementation details. If we ever wanted to change the CSS framework we use for Moodle (say from bootstrap 2 to boostrap 3 or 4) we&#039;d have to find all the places in the code where this tabs template is used and make sure that the HTML is correct in their block overrides.&lt;br /&gt;
&lt;br /&gt;
With that in mind, let&#039;s take one more pass at this template and see if we can improve it slightly again. This time we&#039;re doing to split the template out into 3 templates.&lt;br /&gt;
&lt;br /&gt;
tabs.mustache:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;div id=&amp;quot;{{ uniqid }}-tab-container&amp;quot;&amp;gt;&lt;br /&gt;
	{{$ tabheader }}&lt;br /&gt;
		&amp;lt;ul role=&amp;quot;tablist&amp;quot; class=&amp;quot;nav nav-tabs&amp;quot;&amp;gt;&lt;br /&gt;
			{{$ tablist }}&lt;br /&gt;
				{{# tabs }}&lt;br /&gt;
					{{&amp;gt; core/tab_header_item }}		&lt;br /&gt;
				{{/ tabs }}&lt;br /&gt;
			{{/ tablist }}&lt;br /&gt;
		&amp;lt;/ul&amp;gt;&lt;br /&gt;
	{{/ tabheader }}&lt;br /&gt;
	{{$ tabbody }}&lt;br /&gt;
		&amp;lt;div class=&amp;quot;tab-content&amp;quot;&amp;gt;&lt;br /&gt;
			{{$ tabcontent }}&lt;br /&gt;
				{{# tabs }}&lt;br /&gt;
					{{&amp;gt; core/tab_content_item }}&lt;br /&gt;
				{{/ tabs }}&lt;br /&gt;
			{{/ tabcontent }}&lt;br /&gt;
		&amp;lt;/div&amp;gt;&lt;br /&gt;
	{{/ tabbody }}&lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
{{#js}}&lt;br /&gt;
    require([&#039;jquery&#039;,&#039;core/tabs&#039;], function($, tabs) {&lt;br /&gt;
&lt;br /&gt;
        var container = $(&amp;quot;#{{ uniqid }}-tab-container&amp;quot;);&lt;br /&gt;
        tabs.create(container);&lt;br /&gt;
    });&lt;br /&gt;
{{/js}}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
tab_header_item.mustache&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;li role=&amp;quot;tab&amp;quot;&lt;br /&gt;
		data-selected-class=&amp;quot;active&amp;quot;&lt;br /&gt;
		aria-selected=&amp;quot;false&amp;quot; tabindex=&amp;quot;-1&amp;quot;&amp;gt;&lt;br /&gt;
&lt;br /&gt;
	&amp;lt;a href=&amp;quot;#&amp;quot;&amp;gt;{{$ tabname }}{{{ name }}}{{/ tabname }}&amp;lt;/a&amp;gt;&lt;br /&gt;
&amp;lt;/li&amp;gt;&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
tab_content_item.mustache&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;div role=&amp;quot;tabpanel&amp;quot;&lt;br /&gt;
	class=&amp;quot;tab-pane&amp;quot;&lt;br /&gt;
&lt;br /&gt;
	{{$ tabpanelcontent }}{{{ content }}}{{/ tabpanelcontent }}&lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A summary of the changes:&lt;br /&gt;
* Split the template into 3, moving the tab into it&#039;s own template and the content into it&#039;s own and then including them in the tabs template.&lt;br /&gt;
* Removed the ids from the tabs and content. The javascript would be updating to assign these ids at runtime so that they don&#039;t need to be provided as part of the template context.&lt;br /&gt;
* Added a $tabname block for in the tab_header_item template to make the name flexible on import.&lt;br /&gt;
* Added a $tabpanelcontant block in the tab_content_item template to make the content flexible on import.&lt;br /&gt;
&lt;br /&gt;
Cool, so let&#039;s see what that looks like in our example now:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&amp;lt;html&amp;gt;&lt;br /&gt;
    &amp;lt;header&amp;gt;&amp;lt;title&amp;gt;User Profile&amp;lt;/title&amp;gt;&amp;lt;/header&amp;gt;&lt;br /&gt;
    &amp;lt;body&amp;gt;&lt;br /&gt;
        {{&amp;gt; core/tabs }}&lt;br /&gt;
			{{$ tablist }}&lt;br /&gt;
				{{&amp;lt; core/tab_header_item }}&lt;br /&gt;
					{{$ tabname }}Name{{/ tabname }}&lt;br /&gt;
				{{/ core/tab_header_item }}&lt;br /&gt;
				{{&amp;lt; core/tab_header_item }}&lt;br /&gt;
					{{$ tabname }}Email{{/ tabname }}&lt;br /&gt;
				{{/ core/tab_header_item }}&lt;br /&gt;
			{{/ tablist }}&lt;br /&gt;
			{{$ tabcontent }}&lt;br /&gt;
				{{&amp;lt; core/tab_content_item }}&lt;br /&gt;
					{{$ tabpanelcontent }}Your name is {{ name }}.{{/ tabpanelcontent }}&lt;br /&gt;
				{{/ core/tab_content_item }}&lt;br /&gt;
				{{&amp;lt; core/tab_content_item }}&lt;br /&gt;
					{{$ tabpanelcontent }}Your email address is {{ email }}.{{/ tabpanelcontent }}&lt;br /&gt;
				{{/ core/tab_content_item }}&lt;br /&gt;
			{{/ tabcontent }}&lt;br /&gt;
		{{/ core/tabs }}&lt;br /&gt;
    &amp;lt;/body&amp;gt;&lt;br /&gt;
&amp;lt;/html&amp;gt;&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
And we&#039;re done! After making the changes above we&#039;ve been able to keep the benefits of the previous change to allow the context changes but we&#039;ve also removed the need to copy &amp;amp; paste the HTML everywhere. Instead we&#039;re able to use the child templates with a few additional blocks defined to get the content in there.&lt;br /&gt;
&lt;br /&gt;
Now if we want to change tabs HTML or CSS frameworks we can just change the core tabs templates and this page will receive the updates for free.&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Profiling_PHP&amp;diff=56922</id>
		<title>Profiling PHP</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Profiling_PHP&amp;diff=56922"/>
		<updated>2020-02-13T12:03:44Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* Tideways (replacement for XHProf) */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;PHP has two types of profiler:&lt;br /&gt;
* XHProf is a standard designed for capturing profile traces on live servers. It was originally designed by engineers at Facebook and is suitable for production environments.&lt;br /&gt;
* [http://www.xdebug.org/docs/profiler XDebug] is well known. and understood, and its trace output is supported by tools like [http://kcachegrind.sourceforge.net/html/Home.html KCachegrind]. It is not recommended for production environments.&lt;br /&gt;
&lt;br /&gt;
==Tideways (replacement for XHProf)==&lt;br /&gt;
&lt;br /&gt;
[https://tideways.com/profiler/downloads Tideways] is a PHP7-compatible replacement for XHProf, and support for this is built into Moodle. ([https://tideways.io/ Tideways] is a large, paid-for service, which helps to identify a range of issues with production servers. Whilst the service itself is a paid-for service, the instrumentation tooling is both Open Source, and free.)&lt;br /&gt;
&lt;br /&gt;
When the XHProf PHP extension is installed, the &amp;quot;Profiling&amp;quot;  section is displayed in &amp;quot;Site administration / Development&amp;quot;. And when the profiling setting (profilingenabled) is enabled, a new link &amp;quot;Profiling runs&amp;quot; is also displayed in the Development tab. From this section, apart from access to the profiling runs, you can also import .mpr (Moodle profiling) files. &lt;br /&gt;
&lt;br /&gt;
There are two variants of the plugin. You will almost certainly want the tideways_xhprof plugin.&lt;br /&gt;
&lt;br /&gt;
* [https://tideways.com/profiler/downloads tideways] - the original tool, which includes both xhprof instrumentation, and support for the Tideways service. This version is compatible with:&lt;br /&gt;
** Moodle 3.0.6&lt;br /&gt;
** Moodle 3.1.2&lt;br /&gt;
** Moodle 3.2 onwards&lt;br /&gt;
* [https://github.com/tideways/php-xhprof-extension tideways_xhprof] - a rewritten implementation of the original which only includes the xhprof instrumentation. Compatible with:&lt;br /&gt;
** Moodle 3.1.12&lt;br /&gt;
** Moodle 3.2.9&lt;br /&gt;
** Moodle 3.3.6&lt;br /&gt;
** Moodle 3.4.3&lt;br /&gt;
** Moodle 3.5 onwards&lt;br /&gt;
&lt;br /&gt;
For installation details please see https://github.com/tideways/php-xhprof-extension&lt;br /&gt;
&lt;br /&gt;
See&lt;br /&gt;
* [[Setting up xhprof on Moodle]]&lt;br /&gt;
* http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html&lt;br /&gt;
* https://docs.google.com/presentation/d/1MV4R71UBgPgzM6I9h_yDnYcxIJlgCoLBUDtJJr-TzNI/present#slide=id.i0 presentation about using XHProf&lt;br /&gt;
&lt;br /&gt;
=== Export Xhprof data to plugins ===&lt;br /&gt;
&lt;br /&gt;
Starting at 3.6, Moodle allows for a plugin to handle the Xhprof data and not insert the traces into the database as implemented in (MDL-63031)[https://tracker.moodle.org/browse/MDL-63031]&lt;br /&gt;
&lt;br /&gt;
To disable Moodle from writing traces to the database, add: &amp;quot;$CFG-&amp;gt;disableprofilingtodatabase = False;&amp;quot; into config.php&lt;br /&gt;
&lt;br /&gt;
Plugins will need to provide a _store_profiling_data function to handle the data.&lt;br /&gt;
&lt;br /&gt;
==Xdebug==&lt;br /&gt;
&lt;br /&gt;
[http://xdebug.org/docs/profiler Xdebug] is a powerful PHP debugging tool. The first release of Xdebug was in 2002, since that it keeps growing and remains popular among PHP developers. Among its major features are stack and function tracing, code coverage analysis, remote debugging and scripts profiling. As the page topic suggests, we will focus on its profiling feature, which provides developer with detailed information about the script performance, helps identifying which parts of the code are slow. Collected information is being stored in cachegrind compatible file and can be analysed using one of external tools, such as [http://kcachegrind.sourceforge.net/html/Home.html KCachegrind], [http://sourceforge.net/projects/wincachegrind/ WinCacheGrind], [http://code.google.com/p/xdebugtoolkit/ xdebugtoolkit] or web-based analyser [https://github.com/jokkedk/webgrind#readme Webgrind]. Xdebug is simple to install and operate, it does not require code changes.&lt;br /&gt;
&lt;br /&gt;
===Installing Xdebug extension===&lt;br /&gt;
&lt;br /&gt;
The first step that has to be done is installing Xdebug extension. This procedure depends on the OS you are using, but general idea is to obtain Xdebug php extension and specify full path to it using &#039;&#039;zend_extension&#039;&#039; setting in &#039;&#039;php.inf&#039;&#039; file. Official [http://www.xdebug.org/docs/install Xdebug installation documentation] explains its installation on Windows, installing through PEAR/PECL and compiling from source.&lt;br /&gt;
Xdebug has been packaged for many Linux distributions, so it can be installed using corresponding package management tool. On Debian or Ubuntu, for example one would need to execute:&lt;br /&gt;
&lt;br /&gt;
 # apt-get install php5-xdebug&lt;br /&gt;
&lt;br /&gt;
This will put &#039;&#039;xdebug.so&#039;&#039; in default php modules directory and create &#039;&#039;/etc/php5/conf.d/xdebug.ini&#039;&#039; file with single line:&lt;br /&gt;
&lt;br /&gt;
 zend_extension=/usr/lib/php5/20090626/xdebug.so&lt;br /&gt;
&lt;br /&gt;
Note that this is equal to specifying the same line in &#039;&#039;php.inf&#039;&#039;, example above just reflects split php configuration.&lt;br /&gt;
&lt;br /&gt;
Once the Xdebug extension is installed and specified in php configuration, one may restart the webserver and information about Xdebug should appear in &#039;&#039;phpinfo()&#039;&#039; function output. If not, make sure that &#039;&#039;zend_extension&#039;&#039; line is not commented out, extension file exists in specified location and refer to webserver logs for more details.&lt;br /&gt;
&lt;br /&gt;
===Configuring Xdebug Profiler===&lt;br /&gt;
&lt;br /&gt;
When Xdebug extension is installed, it is time to configure profiling functionality. (If you are running apache2 as your web server and are using split configuration files such as the default apt-get install mentioned above, these settings should be added to &amp;quot;/etc/php5/apache2/conf.d/xdebug.ini&amp;quot;.)  There are number of parameters related to profiling, all of them start with &#039;&#039;xdebug.profiler_&#039;&#039; prefix. First of all, profiler should be enabled. There are two ways of doing it. One way is keeping it always enabled, so profiling information will be generated on every page request:&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_enable=1&lt;br /&gt;
&lt;br /&gt;
Another way is making Xdebug writing profiling information on demand by triggering it with GET/POST or COOKIE variable named &#039;&#039;XDEBUG_PROFILE&#039;&#039;:&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_enable_trigger = 1&lt;br /&gt;
&lt;br /&gt;
This option is preferable for several reasons: profiling data files are relatively large especially on complex scripts and you may run out of disk-space pretty quick, it allows generating profiling information only when you need it, thus it is easier to find the generated file in output directory, finally, on demand profiling can be done on production servers, though it is not recommended. If you have enabled &#039;&#039;xdebug.profiler_enable_trigger&#039;&#039; option, make sure that &#039;&#039;xdebug.profiler_enable&#039;&#039; is disabled, otherwise this will lead to dump file being generated on each request.&lt;br /&gt;
&lt;br /&gt;
Whatever method of profiling enabling you have chosen, profiling data files will be generated on each request (or request with a trigger parameter) in directory specified with &#039;&#039;xdebug.profiler_output_dir&#039;&#039; directive. By default is it set to &#039;&#039;/tmp&#039;&#039;, but you may change it to any more suitable location.&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_output_dir=/tmp&lt;br /&gt;
&lt;br /&gt;
Generated file will be named in accordance with &#039;&#039;xdebug.profiler_output_name&#039;&#039; setting. This setting can handle some specifiers and use them in the file name. Default name pattern is &#039;&#039;cachegrind.out.%p&#039;&#039;; in the actual file name %p will be replaced with process ID value. The fill list of specifier can be found [http://www.xdebug.org/docs/all_settings#trace_output_name here]. More intuitive naming is recommended, so that it is easier to find the file you have just generated in the bunch of others:&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_output_name=cachegrind.out.%R.%t&lt;br /&gt;
&lt;br /&gt;
With this naming pattern, timestamp and script name will be reflected in the file name.&lt;br /&gt;
&lt;br /&gt;
When you are done with configuration, it is time to test it. First of all, the webserver has to be restarted, so that the new config will come into effect. Depending on your operating system and web server, you should be able to restart it with a command similar to:&lt;br /&gt;
&lt;br /&gt;
 sudo service apache2 restart&lt;br /&gt;
&lt;br /&gt;
(This should work for apache2 on several flavours of Linux.)&lt;br /&gt;
&lt;br /&gt;
===Profiling a page===&lt;br /&gt;
&lt;br /&gt;
Now assuming that Xdebug was configured to use a trigger for script profiling, open any php page on your server in your browser having added &#039;&#039;XDEBUG_PROFILE&#039;&#039; parameter to URL string:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;http://servername/moodle2/index.php?XDEBUG_PROFILE&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or if it already has some parameters, just add our trigger to the URL end:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;http://servername/moodle2/mod/forum/view.php?id=5&amp;amp;XDEBUG_PROFILE&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
As a result, the new file should be generated in directory you specified with &#039;&#039;xdebug.profiler_output_dir&#039;&#039; directive:&lt;br /&gt;
&lt;br /&gt;
 cachegrind.out._moodle2_mod_forum_view_php.1289838411&lt;br /&gt;
 cachegrind.out._moodle2_index_php.1289837892&lt;br /&gt;
&lt;br /&gt;
Triggering profiling with POST requests or AJAX queries is also possible without code changes. [https://addons.mozilla.org/en-US/firefox/addon/58688/ Easy Xdebug] plugin for FireFox has profiling toggle button that inserts XDEBUG_PROFILE variable into cookie data, thus making profiling enabled for as long as you wish for all requests. Similar plugins exist for [https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc Chrome] and [https://github.com/benmatselby/xdebug-toggler Safari] browsers.&lt;br /&gt;
&lt;br /&gt;
===Analyzing Xdebug profiling files===&lt;br /&gt;
&lt;br /&gt;
As it was pointed out earlier, profiling data is recoded in cachegrind format, so it can be analysed using one of external tools, such as [https://kcachegrind.github.io/html/Home.html KCachegrind], [http://sourceforge.net/projects/wincachegrind/ WinCacheGrind], [http://code.google.com/p/xdebugtoolkit/ xdebugtoolkit] or web-based analyser [https://github.com/jokkedk/webgrind#readme Webgrind]. Using these tools is pretty simple. I prefer KCachegrind which has a feature to show the matching code if web-server is run on the same box. Xdebug profiler documentation page has a [http://xdebug.org/docs/profiler#misc section] about KCachegrind that worth reading for everyone who starts using KCachegrind.&lt;br /&gt;
&lt;br /&gt;
===Quick summary===&lt;br /&gt;
&lt;br /&gt;
1. Install XDebug extension on your server.&lt;br /&gt;
&lt;br /&gt;
2. Add something like this to your php.ini file:&lt;br /&gt;
 zend_extension = /usr/lib/php5/20090626/xdebug.so&lt;br /&gt;
 xdebug.profiler_enable = 0&lt;br /&gt;
 xdebug.profiler_enable_trigger = 1&lt;br /&gt;
 xdebug.profiler_output_dir = /var/tmp&lt;br /&gt;
 xdebug.profiler_output_name = cachegrind.out.%R.%t&lt;br /&gt;
or add something like this to your .htaccess file&lt;br /&gt;
 php_flag xdebug.profiler_enable off&lt;br /&gt;
 php_flag xdebug.profiler_enable_trigger on&lt;br /&gt;
 php_value xdebug.profiler_output_dir /var/tmp&lt;br /&gt;
 php_value xdebug.profiler_output_name cachegrind.out.%R.%t&lt;br /&gt;
&lt;br /&gt;
3. When you want to profile a page, add &amp;lt;tt&amp;gt;&amp;amp;XDEBUG_PROFILE&amp;lt;/tt&amp;gt; to the end of the URL.&lt;br /&gt;
&lt;br /&gt;
4. Open the &amp;lt;tt&amp;gt;cachegrind.out....&amp;lt;/tt&amp;gt; file that is generated with one of the tools mentioned above.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==See also==&lt;br /&gt;
&lt;br /&gt;
* [http://moodle.org/mod/forum/discuss.php?d=162045 Forum thread about profiling Moodle 2.0]&lt;br /&gt;
XHProf articles:&lt;br /&gt;
* [https://docs.google.com/present/view?id=dcbkgbgf_45fbg3rnmk&amp;amp; Presentation about XHProf]&lt;br /&gt;
* [http://techportal.ibuildings.com/2009/12/01/profiling-with-xhprof/ Profiling with XHProf]&lt;br /&gt;
* [http://www.open.ac.uk/blogs/XHProf/?page_id=46 XHProf – Profiling and Reporting] from Moodle perspective written by [http://moodle.org/user/view.php?id=264538&amp;amp;course=5 James Brisland]&lt;br /&gt;
Xdebug articles:&lt;br /&gt;
* [http://devzone.zend.com/article/2803-Introducing-xdebug Introducing xdebug]&lt;br /&gt;
* [http://blog.teamlazerbeez.com/2010/05/04/xdebug-quickstart-profiling-in-php/ Xdebug Quickstart: Profiling in PHP]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Question_types&amp;diff=56753</id>
		<title>Question types</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Question_types&amp;diff=56753"/>
		<updated>2019-12-19T12:04:47Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* File layout */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Template:Question_engine_2}}&lt;br /&gt;
=Question type plug in development=&lt;br /&gt;
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 .&lt;br /&gt;
&lt;br /&gt;
For instructions on making a question type for versions of Moodle prior to Moodle 2.1, see [[Question_type_plugin_how_to]].&lt;br /&gt;
&lt;br /&gt;
Previous section: [[Developing a Question Behaviour|Developing a Question Behaviour]]&lt;br /&gt;
&lt;br /&gt;
==Existing question type plug ins are helpful guides==&lt;br /&gt;
&lt;br /&gt;
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&amp;amp;id=29 the question type category of the Moodle plugins database].&lt;br /&gt;
&lt;br /&gt;
===Existing question types and some of their features===&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
* Questions included in Moodle&lt;br /&gt;
** true false, short answer&lt;br /&gt;
*** simplest question types&lt;br /&gt;
** Essay question type (essay)&lt;br /&gt;
*** manually not automatically graded.&lt;br /&gt;
** Calculated question &lt;br /&gt;
*** Uses a multipage question editing form&lt;br /&gt;
** Multiple choice (multichoice)&lt;br /&gt;
*** there is actually no reason why you should only have a single &amp;lt;tt&amp;gt;question_definition&amp;lt;/tt&amp;gt; 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 &amp;lt;tt&amp;gt;question_type::make_question_instance&amp;lt;/tt&amp;gt; and &amp;lt;tt&amp;gt;question_definition::get_renderer&amp;lt;/tt&amp;gt; methods.&lt;br /&gt;
* Contrib questions&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_ddwtos Drag and drop into text (ddwtos)] &lt;br /&gt;
*** Use of YUI js module to add more interactivity.&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_ddmarker Drag and drop markers question type (ddmarker)]&lt;br /&gt;
*** Use of YUI js module to add more interactivity.&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_ddimageortext Drag and drop (image or text) onto image (ddimageortext)]&lt;br /&gt;
*** inherits code from Select missing words (gapselect).&lt;br /&gt;
*** also contains base classes which inherit from Select missing words (gapselect) and are used by Drag and drop markers&lt;br /&gt;
*** Use of YUI js module to add more interactivity.&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_oumultiresponse OU multiple response (oumultiresponse)]&lt;br /&gt;
*** 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.&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_pmatch Pmatch question type (pmatch)]&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_pmatchjme Pattern match with JME editor (pmatchjme)]&lt;br /&gt;
*** Embeds a JAVA applet in the question which collects the student response and sends that to the server.&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qbehaviour_opaque Question managed by a remote engine (opaque)]&lt;br /&gt;
*** communicates with an external system by a web service protocol based on SOAP to &amp;quot;delegate the rendering of questions, the scoring of responses and the generation of feedback to a remote question engine.&amp;quot; See https://docs.moodle.org/dev/Opaque&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_gapselect Select missing words (gapselect)]&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_varnumeric Variable numeric question type (varnumeric)]&lt;br /&gt;
*** Code inherited from Variable numeric set.&lt;br /&gt;
** [https://moodle.org/plugins/view.php?plugin=qtype_varnumericset Variable numeric set question type (varnumericset)]&lt;br /&gt;
&lt;br /&gt;
==Question type plug in template==&lt;br /&gt;
&lt;br /&gt;
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. &lt;br /&gt;
&lt;br /&gt;
==The question engine itself is well commented==&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
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]].&lt;br /&gt;
&lt;br /&gt;
===Changes in the question type plug in api between Moodle versions===&lt;br /&gt;
&lt;br /&gt;
[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.&lt;br /&gt;
&lt;br /&gt;
==File layout==&lt;br /&gt;
&lt;br /&gt;
Question types live in a folder in &amp;lt;tt&amp;gt;question/type&amp;lt;/tt&amp;gt;. The layout inside this folder follows the typical layout for a Moodle plugin. For example, inside the &amp;lt;tt&amp;gt;question/type/mytype/&amp;lt;/tt&amp;gt; folder we would have:&lt;br /&gt;
&lt;br /&gt;
; 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.&lt;br /&gt;
; questiontype.php : Defines the &amp;lt;tt&amp;gt;qtype_mytype&amp;lt;/tt&amp;gt; class. This must extend &amp;lt;tt&amp;gt;question_type&amp;lt;/tt&amp;gt;.&lt;br /&gt;
; question.php : This contains the definition of the &amp;lt;tt&amp;gt;qtype_mytype_question&amp;lt;/tt&amp;gt; class, which should extend the &amp;lt;tt&amp;gt;question_definition&amp;lt;/tt&amp;gt; base class.&lt;br /&gt;
; renderer.php : This contains the definition of the &amp;lt;tt&amp;gt;qtype_mytype_renderer&amp;lt;/tt&amp;gt; class, which should extend the &amp;lt;tt&amp;gt;qtype_renderer&amp;lt;/tt&amp;gt; base class.&lt;br /&gt;
; 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.&lt;br /&gt;
; 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 : &lt;br /&gt;
&lt;br /&gt;
    $string[&#039;pluginname&#039;] = &#039;YOURQTYPENAME&#039;;&lt;br /&gt;
    $string[&#039;pluginname_help&#039;] = &#039;Create a .. description of your question type&#039;; // This is the text of the help icon show by the heading above the add/edit form when a question of this type is being edited.&lt;br /&gt;
    $string[&#039;pluginname_link&#039;] = &#039;question/type/YOURQTYPENAME&#039;;&lt;br /&gt;
    $string[&#039;pluginnameadding&#039;] = &#039;Adding a YOURQTYPENAME question&#039;;&lt;br /&gt;
    $string[&#039;pluginnameediting&#039;] = &#039;Editing a YOURQTYPENAME question&#039;;&lt;br /&gt;
    $string[&#039;pluginnamesummary&#039;] = &#039;A YOURQTYPENAME question type which allows...&#039;; // This is the text relating to this question type shown in the question-type chooser dialogue.&lt;br /&gt;
&lt;br /&gt;
; 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.&lt;br /&gt;
; db/install.xml, db/upgrade.php : For creating any database tables required, [[Installing_and_upgrading_plugin_database_tables|as normal]]. See [[#Database_tables]] below.&lt;br /&gt;
; db/access.php : Defines any capabilities required by this question type. This is very rarely needed.&lt;br /&gt;
; 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/.&lt;br /&gt;
; 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 &#039;que&#039; and &#039;YOURQTYPENAME&#039;.&lt;br /&gt;
; 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.)&lt;br /&gt;
; backup/moodle2/ : contains the files to implement backup and restore for your question type.&lt;br /&gt;
; 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]].&lt;br /&gt;
; 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.&lt;br /&gt;
; 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.)&lt;br /&gt;
&lt;br /&gt;
==Database tables==&lt;br /&gt;
&lt;br /&gt;
Note that question types should only have database tables for the question definition. All runtime data is managed by the question engine.&lt;br /&gt;
&lt;br /&gt;
Question definitions should use the core table &amp;lt;tt&amp;gt;question&amp;lt;/tt&amp;gt;, and can use the core table &amp;lt;tt&amp;gt;question_answers&amp;lt;/tt&amp;gt;. You only need to define database tables if your question definition requires extra information that cannot be stored in either of these.&lt;br /&gt;
&lt;br /&gt;
==Question type and question definition classes==&lt;br /&gt;
&lt;br /&gt;
===The question definition class is in question.php===&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
===The question type class is in questiontype.php===&lt;br /&gt;
&lt;br /&gt;
In contrast, the question type class represents the question type. For example, the qtype_shortanswer class represents the &#039;short answer&#039; 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.&lt;br /&gt;
&lt;br /&gt;
==Renderer class==&lt;br /&gt;
&lt;br /&gt;
Renderers are all about generating HTML output. The overall output of questions is controlled by the &amp;lt;tt&amp;gt;core_question_renderer::question(...)&amp;lt;/tt&amp;gt;, 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]].&lt;br /&gt;
&lt;br /&gt;
Once again, in what follows, I only list the methods your are most likely to want to override.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
===formulation_and_controls===&lt;br /&gt;
&lt;br /&gt;
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&#039;s response.&lt;br /&gt;
&lt;br /&gt;
The output code must respect the &amp;lt;tt&amp;gt;question_display_options&amp;lt;/tt&amp;gt; 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 &amp;lt;tt&amp;gt;-&amp;gt;readonly&amp;lt;/tt&amp;gt; option.&lt;br /&gt;
&lt;br /&gt;
===specific_feedback===&lt;br /&gt;
&lt;br /&gt;
Anything returned by this method is included in the &#039;outcome&#039; 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&#039;t have to worry about testing that.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
===correct_response===&lt;br /&gt;
&lt;br /&gt;
This would also be included in the &#039;outcome&#039; area. This should be an automatically generated (from the question definition) display of what the correct answer to the question is.&lt;br /&gt;
&lt;br /&gt;
==Unit tests==&lt;br /&gt;
&lt;br /&gt;
For a general introduction, see the [[PHPUnit|Moodle unit testing documentation]].&lt;br /&gt;
&lt;br /&gt;
The most important parts of your question type to test are the parts of the &amp;lt;tt&amp;gt;question_definition&amp;lt;/tt&amp;gt; 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.&lt;br /&gt;
&lt;br /&gt;
Another useful type of test for questions are &#039;walkthrough&#039; 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].&lt;br /&gt;
&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
==Manually testing a question type==&lt;br /&gt;
&lt;br /&gt;
The following provides a thorough test of a new question type. A lot of the following can now be done with [[Acceptance_testing|Behat]].&lt;br /&gt;
&lt;br /&gt;
# Create some new questions of your type, exercising each significantly different combination of options.&lt;br /&gt;
# 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.&lt;br /&gt;
# Try typing invalid input into the editing form, and ensure it is rejected.&lt;br /&gt;
# 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.&lt;br /&gt;
# Add your questions to some quizzes, using a range of behaviours, and different numbers of questions per page.&lt;br /&gt;
# 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.&lt;br /&gt;
# Now log in as a student and take the quizzes for real.&lt;br /&gt;
# If the question type uses complex CSS or JavaScript, repeat this testing in different web browsers.&lt;br /&gt;
# View all of the quiz reports, and ensure that they correctly display the information about your questions.&lt;br /&gt;
# Backup the course, restore it as a new course, and ensure that all your questions have been copied across accurately.&lt;br /&gt;
# 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).&lt;br /&gt;
# 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.&lt;br /&gt;
# 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&#039;t end up with broken image links.&lt;br /&gt;
# Move the category containing the questions with images to a new context in the question bank, and make sure that the image links don&#039;t break.&lt;br /&gt;
# Check that all the unit tests for your question type pass.&lt;br /&gt;
# Run code-checker (https://moodle.org/plugins/view.php?plugin=local_codechecker) over your plugin to check the coding style.&lt;br /&gt;
# Check your question type against Accessibility guidelines, for example the [http://www.w3.org/WAI/intro/wcag.php Web Content Accessibility Guidelines].&lt;br /&gt;
&lt;br /&gt;
==See also==&lt;br /&gt;
&lt;br /&gt;
Next section: [[Using_the_question_engine_from_module|Using the question engine from a module]].&lt;br /&gt;
&lt;br /&gt;
* The PHP documenter comments that explain the purposes of every method in the question engine code.&lt;br /&gt;
* Back to [[Question_Engine_2|Question Engine 2]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Plugins]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Commit_cheat_sheet&amp;diff=56734</id>
		<title>Commit cheat sheet</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Commit_cheat_sheet&amp;diff=56734"/>
		<updated>2019-12-12T10:27:07Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* Provide clear commit messages */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;You can consider this page as a list to check before you submit a patch for inclusion into Moodle.&lt;br /&gt;
&lt;br /&gt;
== Split your work into a logical set of patches ==&lt;br /&gt;
&lt;br /&gt;
Keep in mind that your commits will be reviewed before they are accepted. If the patch does one clear thing and does it well, the review process is fun. Git allows you to prepare patches on your branch into a sequence of logical steps. For example, when changing some API, divide the change into two steps. In the first commit, change the API. In the following commit, change all places that use the API.&lt;br /&gt;
&lt;br /&gt;
== Provide clear commit messages ==&lt;br /&gt;
&lt;br /&gt;
Consider the commit message as an email for the developer who would explore the change in the future. We recommend to follow common Git guidelines for formatting. The first line of commit message is generally treated as commit subject and ideally should not exceed 72 characters. Include the MDL issue number and the area/component at the beginning of the subject line. Please note that &#039;code area&#039; refers to the code areas being affected by this commit - correct the MDL&#039;s components reported against if needed. If you are writing more than one line, the second line must be empty. Break lines 3 and following to not exceed 132 characters (ideally don&#039;t exceed 80 chars per line).&lt;br /&gt;
&lt;br /&gt;
    MDL-xxxxx code area: short description of the patch&lt;br /&gt;
    &lt;br /&gt;
    The subject line is followed by an empty line and then a paragraph or two of&lt;br /&gt;
    a longer description follows if necessary. This longer description is useful&lt;br /&gt;
    for issues with longer history of comments in the linked MDL so that it&lt;br /&gt;
    summarizes the patch without the need to go through the whole discussion.&lt;br /&gt;
    &lt;br /&gt;
    Obviously, avoid messages like &amp;quot;as agreed in the chat&amp;quot; as they will become&lt;br /&gt;
    useless after a relatively short time.&lt;br /&gt;
&lt;br /&gt;
Most of Git tools are optimised for this format and they can display the log of commits best then.&lt;br /&gt;
&lt;br /&gt;
::Tip: the command &amp;lt;tt&amp;gt;git log --no-merges&amp;lt;/tt&amp;gt; will show you recent commit messages. Hopefully those are all good examples to copy.&lt;br /&gt;
&lt;br /&gt;
== Names in the commit message ==&lt;br /&gt;
&lt;br /&gt;
Retain the authorship of the patch. If the patch was submitted by someone else - for example a community member who published it in the tracker or in a forum - use the --author parameter. Make sure that your &#039;&#039;real&#039;&#039; name and contact email are recorded in patch. We use real names written in capital letters like &amp;quot;John Smith&amp;quot;. Please do not use names like &amp;lt;strike&amp;gt;&amp;quot;john smith&amp;quot;, &amp;quot;John S&amp;quot;, &amp;quot;johnny7887&amp;quot;&amp;lt;/strike&amp;gt;. If you use --author parameter, apply the same rules for the name of the author. See almost any Git tutorial on how to set your name and email in the global Git configuration.&lt;br /&gt;
&lt;br /&gt;
== Provide clear and operational instructions to test your patch ==&lt;br /&gt;
&lt;br /&gt;
In the tracker issue, please describe how the change can be tested. Please avoid vague phrases like &amp;quot;Make sure there is no regression in the core&amp;quot; or &amp;quot;Test all places where XXX is used&amp;quot;. Also, try to avoid requiring resources that are really difficult to gather, if possible - as in &amp;quot;Use production data from a server with 100.000+ students&amp;quot;. &lt;br /&gt;
&lt;br /&gt;
If you have permission, edit the tracker issue and put the testing instructions into the &amp;quot;Testing instructions&amp;quot; field. If you do not have permission to edit that field, then write them in a comment on the tracker issue.&lt;br /&gt;
&lt;br /&gt;
It helps if you state your estimation of the testing difficulty so that testers can pick issues for them:&lt;br /&gt;
&lt;br /&gt;
;Easy : (average community member should be able to test it) - can be tested pretty easily via the web interface only at a public test site&lt;br /&gt;
;Moderate : (knowledgeable administrator should be able to test it) - requires local installation, for example to test some 1.9 -&amp;gt; 2.0 upgrade steps or some non-standard environment (for example MNet features, specific platform etc)&lt;br /&gt;
;Hard : (development skills are required to test it) - for example may require data hacking at SQL level to simulate data corruption or modifying the code to reproduce the problem&lt;br /&gt;
&lt;br /&gt;
Example testing instructions:&lt;br /&gt;
&lt;br /&gt;
    (difficulty: easy, requires teacher access to a course)&lt;br /&gt;
    1. Log in as a teacher and go to a course&lt;br /&gt;
    2. Turn editing mode on&lt;br /&gt;
    3. TEST: Make sure that the control icons appear next to the activity titles&lt;br /&gt;
    4. Turn editing mode off&lt;br /&gt;
    5. TEST: Make sure that the control icons are not displayed now&lt;br /&gt;
&lt;br /&gt;
== Introducing new strings ==&lt;br /&gt;
&lt;br /&gt;
Firstly, think twice and try to think in a non-English language. Any string you introduce is supposed to be translated by translators who usually do it for free in their own time. Do not waste their time by using get_string() for debugging messages that are likely to almost never appear. It is warmly recommended to let Helen review your strings before you submit them. This way we can keep the terminology and the style consistent. When introducing new strings, keep them alphabetically sorted. Using a self-descriptive names of the string identifier and the placeholder properties helps the translators to guess the context. Compare the following&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;grade&#039;] = &#039;Grade {$a}&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
with&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;maxgradevalue&#039;] = &#039;Grade {$a-&amp;gt;value}&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the first case, it is pretty difficult to guess whether the &amp;quot;Grade&amp;quot; in the string is a noun (as in &amp;quot;Grade 12/30&amp;quot;) or a verb (as in &amp;quot;Grade submission&amp;quot;). In many languages, the translation depends on it. The second case is more self-descriptive as it indicates that the placeholder will contain a value.&lt;br /&gt;
&lt;br /&gt;
Another good example of how _not_ to name string identifiers would be something like&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;post&#039;] = &#039;Post&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that there is no clue if the &amp;quot;post&amp;quot; here is used as a noun (e.g. describing one particular forum post) or a verb (such as an action of posting into a forum). In many languages, the translation is different for either case.&lt;br /&gt;
&lt;br /&gt;
See [[Help strings]] if you are introducing a new help string.&lt;br /&gt;
&lt;br /&gt;
== Include AMOS script in the commit if needed ==&lt;br /&gt;
&lt;br /&gt;
If you change the identifier of a string or split a string into two forks, provide a script for AMOS in the commit message. Since Moodle 2.0, the translations are kept on separated branches again. The AMOS plugin at http://lang.moodle.org tracks the changes in string files and automatically records modifications, additions and removals of strings. Therefore strings can be re-worded freely on stable branches and should be removed from the master branch if they are not needed any more (do not remove strings from stable branches).&lt;br /&gt;
&lt;br /&gt;
If you change the identifier of the string (that is the key in the $string array), move the string from one file to another or you are introducing a new string as a copy of some current one, you should provide instructions for AMOS so that the action can be applied in all language packs. That will save valuable translators&#039; time. Instructions for AMOS are being put into the commit message of a commit that modifies the original English string files. The commit message containing such a script may look like this:&lt;br /&gt;
&lt;br /&gt;
    MDL-xxxxx code area: short description of the patch&amp;lt;br /&amp;gt;&lt;br /&gt;
    It is recommended to leave a blank line between the commit message and the&lt;br /&gt;
    script block.&amp;lt;br /&amp;gt;&lt;br /&gt;
    AMOS BEGIN&lt;br /&gt;
     MOV [configfoobar,core_admin],[foobar_desc,core_admin]&lt;br /&gt;
     CPY [submission,mod_assignment],[submission,mod_workshop]&lt;br /&gt;
    AMOS END&lt;br /&gt;
&lt;br /&gt;
See [[Languages/AMOS#AMOS_script]] for more details of the syntax. See [http://git.moodle.org/gw?p=moodle.git&amp;amp;a=search&amp;amp;h=HEAD&amp;amp;st=commit&amp;amp;s=AMOS+BEGIN the log history] real examples of usage.&lt;br /&gt;
&lt;br /&gt;
==Removing strings==&lt;br /&gt;
&lt;br /&gt;
When a new feature completely replaces an existing feature, any strings which are no longer used should be removed from the code in the master branch. See [[String deprecation]] for more information.&lt;br /&gt;
&lt;br /&gt;
== Main version changes ==&lt;br /&gt;
&lt;br /&gt;
If your commit requires a change to the main version number in version.php (and corresponding upgrade in lib/db/upgrade.php), you should increment that version number by .01, and let integrators deal with merge conflicts (for example if multiple people that week submit several .01 updates).&lt;br /&gt;
&lt;br /&gt;
(Note there may be policies about avoiding the type of changes which require version.php updates, especially in stable branches.)&lt;br /&gt;
&lt;br /&gt;
[[Category:Git]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Tag_API&amp;diff=56479</id>
		<title>Tag API</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Tag_API&amp;diff=56479"/>
		<updated>2019-09-27T11:36:48Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* Displaying tags next to the item */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Moodle 3.1}}&lt;br /&gt;
&lt;br /&gt;
==Tag API overview==&lt;br /&gt;
&lt;br /&gt;
The Tag API allows you to assign labels to information in Moodle. This makes finding this information easier and also facilitates the grouping of similar information. The Tag API allows you to create, modify, delete and search tags in the Moodle system. The main tag related functions can be found in the tag/classes/tag.php file. For a through overview of all of the functions available for working with Tags please see methods in core_tag_tag, core_tag_collection and core_tag_area classes, however the following examples should give you a general understanding of how to get started with tags.&lt;br /&gt;
&lt;br /&gt;
This page describes API in Moodle 3.1 and above, for earlier versions see [[Tag API before 3.1]]&lt;br /&gt;
&lt;br /&gt;
==Tag API usage==&lt;br /&gt;
&lt;br /&gt;
When user tags something a &#039;&#039;&#039;tag instance&#039;&#039;&#039; is created in the database linking the item to the actual &#039;&#039;&#039;tag&#039;&#039;&#039;. If tag did not exist before it is created automatically. Do not confuse these two entities - deleting the tag instance does not normally delete tag, however deleting tag deletes all tag instances associated with it. &lt;br /&gt;
&lt;br /&gt;
Developers define &#039;&#039;&#039;tag areas&#039;&#039;&#039; the areas that can be tagged, examples are:&lt;br /&gt;
* blog posts&lt;br /&gt;
* courses&lt;br /&gt;
* users (tags represent user interests)&lt;br /&gt;
* activity modules&lt;br /&gt;
* questions&lt;br /&gt;
* wiki pages&lt;br /&gt;
&lt;br /&gt;
Each tag area is identified by two attributes - component and itemtype. &#039;&#039;Itemtype must be a name of a table in the database.&#039;&#039; Component is the core component or plugin responsible for the tagging. This way the same DB table (for example &#039;user&#039; or &#039;course&#039;) may be independently tagged by several components. Administrator or manager is able to manage the tag areas, collections and tags inside them on the [https://docs.moodle.org/en/Managing_tags Managing tags] page. Users are able to search tags and view all items tagged with them that they have access to.&lt;br /&gt;
&lt;br /&gt;
===Defining a tag area===&lt;br /&gt;
&lt;br /&gt;
First, developer must define the tag areas in the file &#039;&#039;&#039;db/tag.php&#039;&#039;&#039;. This will usually look like:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$tagareas = array(&lt;br /&gt;
    array(&lt;br /&gt;
        &#039;itemtype&#039; =&amp;gt; &#039;wiki_pages&#039;,  // This must be a name of the database table (without prefix).&lt;br /&gt;
        &#039;component&#039; =&amp;gt; &#039;mod_wiki&#039;, // This can be omitted for plugins since it can only be full frankenstyle name of the plugin.&lt;br /&gt;
        &#039;callback&#039; =&amp;gt; &#039;mod_wiki_get_tagged_pages&#039;,&lt;br /&gt;
        &#039;callbackfile&#039; =&amp;gt; &#039;/mod/wiki/locallib.php&#039;,&lt;br /&gt;
    ),&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
You will also need to add language string, for the example above it will be &#039;&#039;&#039;$string[&#039;tagarea_wiki_pages&#039;] = &#039;Wiki pages&#039;;&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
There are more options such as specifying the default value for &amp;quot;Standard tags&amp;quot;, having a fixed collection or excluding from search. They can be found in comments in [[https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]]&lt;br /&gt;
&lt;br /&gt;
After making changes to db/tag.php plugin developer must bump the plugin version in &#039;&#039;&#039;version.php&#039;&#039;&#039; and run upgrade script. This usually applies to any changes in the db/ folder.&lt;br /&gt;
&lt;br /&gt;
===Adding tags element to the editing form===&lt;br /&gt;
&lt;br /&gt;
After tag area is defined it should appear on &amp;quot;Manage tags&amp;quot; page. Now it is time to allow users to add/change tags when editing the item. Here is an example from Wiki module:&lt;br /&gt;
&lt;br /&gt;
1. Add a &#039;tags&#039; form element to the editing form:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;tags&#039;, &#039;tags&#039;, get_string(&#039;tags&#039;), array(&#039;itemtype&#039; =&amp;gt; &#039;wiki_pages&#039;, &#039;component&#039; =&amp;gt; &#039;mod_wiki&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This element will automatically check if the tag area is disabled by the manager and will not display anything in this case. However if you want to add a header you need to check if tag area is enabled add this:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if (core_tag_tag::is_enabled(&#039;mod_wiki&#039;, &#039;wiki_pages&#039;)) {&lt;br /&gt;
    $mform-&amp;gt;addElement(&#039;header&#039;, &#039;tagshdr&#039;, get_string(&#039;tags&#039;, &#039;tag&#039;));&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
2. Save the form data&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if ($data = $form-&amp;gt;get_data()) {&lt;br /&gt;
    // Do some other processing here, if this is a new page (item) you need to insert it in the DB and obtain id.&lt;br /&gt;
    // $pageid = $data-&amp;gt;id;&lt;br /&gt;
    core_tag_tag::set_item_tags(&#039;mod_wiki&#039;, &#039;wiki_pages&#039;, $pageid, $modulecontext, $data-&amp;gt;tags);&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
It is important to specify the correct context in this function. Note that $data-&amp;gt;tags will always be returned by the form, even if the area is disabled, however core_tag_tag::set_item_tags() will not change or reset tags if the tag area is disabled.&lt;br /&gt;
&lt;br /&gt;
3. Populate the form with existing tags before calling $form-&amp;gt;set_data($data):&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$data = $DB-&amp;gt;get_record(&#039;wiki_pages&#039;, array(&#039;id&#039; =&amp;gt; $this-&amp;gt;page-&amp;gt;id)); // Well, it&#039;s more complicated than that of course....&lt;br /&gt;
$data-&amp;gt;tags = core_tag_tag::get_item_tags_array(&#039;mod_wiki&#039;, &#039;wiki_pages&#039;, $this-&amp;gt;page-&amp;gt;id);&lt;br /&gt;
$form-&amp;gt;set_data($data);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Always test the code with tag area enabled and disabled.&lt;br /&gt;
&lt;br /&gt;
===Displaying tags next to the item===&lt;br /&gt;
&lt;br /&gt;
Example of displaying of the tags are user interests on the user profile page. User can see the list of interests, each of them is a link that leads to the page that shows all items tagged with this tag.&lt;br /&gt;
&lt;br /&gt;
Here is the code used by Wiki module to display tags the page is tagged with:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
echo $OUTPUT-&amp;gt;tag_list(core_tag_tag::get_item_tags(&#039;mod_wiki&#039;, &#039;wiki_pages&#039;, $page-&amp;gt;id), null, &#039;wiki-tags&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you will need to load the tags for a lot of different item ids, when use core_tag_tag::get_items_tags to load them all in a single DB query.&lt;br /&gt;
&lt;br /&gt;
===Deleting and clearing tags===&lt;br /&gt;
&lt;br /&gt;
Cron will automatically remove tag instances that point to non existing items, however it is a good habit to delete tags when the record is deleted.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Please note:&#039;&#039;&#039; If you have created a course activity that uses tags you should also remember to delete the tags during a course reset by adding code to the reset course callbacks. First you want to add a checkbox that a user can check if they wish to delete the tags, then code that handles the case when the checkbox has been checked. Example -&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
 * The elements to add the course reset form.&lt;br /&gt;
 *&lt;br /&gt;
 * @param moodleform $mform&lt;br /&gt;
 */&lt;br /&gt;
function book_reset_course_form_definition(&amp;amp;$mform) {&lt;br /&gt;
    $mform-&amp;gt;addElement(&#039;header&#039;, &#039;bookheader&#039;, get_string(&#039;modulenameplural&#039;, &#039;book&#039;));&lt;br /&gt;
    $mform-&amp;gt;addElement(&#039;checkbox&#039;, &#039;reset_book_tags&#039;, get_string(&#039;removeallbooktags&#039;, &#039;book&#039;));&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
/**&lt;br /&gt;
 * This function is used by the reset_course_userdata function in moodlelib.&lt;br /&gt;
 * @param $data the data submitted from the reset course.&lt;br /&gt;
 * @return array status array&lt;br /&gt;
 */&lt;br /&gt;
function book_reset_userdata($data) {&lt;br /&gt;
    global $DB;&lt;br /&gt;
&lt;br /&gt;
    $status = [];&lt;br /&gt;
&lt;br /&gt;
    if (!empty($data-&amp;gt;reset_book_tags)) {&lt;br /&gt;
        // Loop through the books and remove the tags from the chapters.&lt;br /&gt;
        if ($books = $DB-&amp;gt;get_records(&#039;book&#039;, array(&#039;course&#039; =&amp;gt; $data-&amp;gt;courseid))) {&lt;br /&gt;
            foreach ($books as $book) {&lt;br /&gt;
                if (!$cm = get_coursemodule_from_instance(&#039;book&#039;, $book-&amp;gt;id)) {&lt;br /&gt;
                    continue;&lt;br /&gt;
                }&lt;br /&gt;
&lt;br /&gt;
                $context = context_module::instance($cm-&amp;gt;id);&lt;br /&gt;
                core_tag_tag::delete_instances(&#039;mod_book&#039;, null, $context-&amp;gt;id);&lt;br /&gt;
            }&lt;br /&gt;
        }&lt;br /&gt;
&lt;br /&gt;
        $status[] = [&lt;br /&gt;
            &#039;component&#039; =&amp;gt; get_string(&#039;modulenameplural&#039;, &#039;book&#039;),&lt;br /&gt;
            &#039;item&#039; =&amp;gt; get_string(&#039;tagsdeleted&#039;, &#039;book&#039;),&lt;br /&gt;
            &#039;error&#039; =&amp;gt; false&lt;br /&gt;
        ];&lt;br /&gt;
    }&lt;br /&gt;
&lt;br /&gt;
    return $status;&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The functions used to delete the tags are -&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
core_tag_tag::remove_all_item_tags($component, $itemtype, $itemid, $tiuserid = 0) // Removes all tag instances associated with an item.&lt;br /&gt;
core_tag_tag::delete_instances($component, $itemtype = null, $contextid = null) // Removes tag instances in bulk. Here $component is mandatory in this method, either itemtype or contextid or neither or both can be specified.&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===Backup and restore===&lt;br /&gt;
&lt;br /&gt;
When you tag contents inside the course the plugin has to hook into backup and restore and process necessary tags. This is especially important for the contents inside activity modules, such as wiki pages or forum posts. Questions in the course question bank also backup and restore their tags.&lt;br /&gt;
&lt;br /&gt;
You can choose to backup and restore tags for each item individually (as it is done in mod_wiki) OR backup all tags in the context at once (as it is done in mod_glossary or mod_forum). Second option is preferable for performance reasons. Make sure to take into account $userinfo (whether user information is backed up / restored), for example wiki pages is not user information but glossary entries are, tags on them follow the same rule.&lt;br /&gt;
&lt;br /&gt;
This is an example from Glossary module that can be found in &#039;&#039;&#039;backup_glossary_stepslib.php&#039;&#039;&#039;:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
protected function define_structure() {&lt;br /&gt;
    // ...&lt;br /&gt;
    $tags = new backup_nested_element(&#039;entriestags&#039;);&lt;br /&gt;
    $tag = new backup_nested_element(&#039;tag&#039;, array(&#039;id&#039;), array(&#039;itemid&#039;, &#039;rawname&#039;));&lt;br /&gt;
    // ...&lt;br /&gt;
    $glossary-&amp;gt;add_child($tags); // Note that parent node is the glossary, not glossary entry, however the individual entries are tagged.&lt;br /&gt;
    $tags-&amp;gt;add_child($tag);&lt;br /&gt;
    // ...&lt;br /&gt;
    if ($userinfo &amp;amp;&amp;amp; core_tag_tag::is_enabled(&#039;mod_glossary&#039;, &#039;glossary_entries&#039;)) {&lt;br /&gt;
        $tag-&amp;gt;set_source_sql(&#039;SELECT t.id, ti.itemid, t.rawname&lt;br /&gt;
                                FROM {tag} t&lt;br /&gt;
                                JOIN {tag_instance} ti ON ti.tagid = t.id&lt;br /&gt;
                               WHERE ti.itemtype = ?&lt;br /&gt;
                                 AND ti.component = ?&lt;br /&gt;
                                 AND ti.contextid = ?&#039;, array(&lt;br /&gt;
            backup_helper::is_sqlparam(&#039;glossary_entries&#039;),&lt;br /&gt;
            backup_helper::is_sqlparam(&#039;mod_glossary&#039;),&lt;br /&gt;
            backup::VAR_CONTEXTID));&lt;br /&gt;
    }&lt;br /&gt;
    // ...&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
And this in the &#039;&#039;&#039;restore_glossary_stepslib.php&#039;&#039;&#039;:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
protected function define_structure() {&lt;br /&gt;
    // ...&lt;br /&gt;
    if ($userinfo) {&lt;br /&gt;
        $paths[] = new restore_path_element(&#039;glossary_entry_tag&#039;, &#039;/activity/glossary/entriestags/tag&#039;);&lt;br /&gt;
    }&lt;br /&gt;
    // ...&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
protected function process_glossary_entry_tag($data) {&lt;br /&gt;
    $data = (object)$data;&lt;br /&gt;
&lt;br /&gt;
    if (!core_tag_tag::is_enabled(&#039;mod_glossary&#039;, &#039;glossary_entries&#039;)) { // Tags disabled on this site, nothing to process.&lt;br /&gt;
        return;&lt;br /&gt;
    }&lt;br /&gt;
&lt;br /&gt;
    $tag = $data-&amp;gt;rawname;&lt;br /&gt;
    if (!$itemid = $this-&amp;gt;get_mappingid(&#039;glossary_entry&#039;, $data-&amp;gt;itemid)) {&lt;br /&gt;
        // Orphaned tag, we could not find the glossary entry for it - ignore.&lt;br /&gt;
        return;&lt;br /&gt;
    }&lt;br /&gt;
&lt;br /&gt;
    $context = context_module::instance($this-&amp;gt;task-&amp;gt;get_moduleid());&lt;br /&gt;
    core_tag_tag::add_item_tag(&#039;mod_glossary&#039;, &#039;glossary_entries&#039;, $itemid, $context, $tag);&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===Search callback===&lt;br /&gt;
&lt;br /&gt;
This is the most difficult part of Tag API. When user searches for the items tagged with a specific tag only the items user has access to must be returned. Running access check on all items can be very costly. Class &#039;&#039;&#039;core_tag_index_builder&#039;&#039;&#039; can help with retrieving and caching records, especially inside the courses or activity modules.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
function mod_wiki_get_tagged_pages($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {&lt;br /&gt;
    // Find items.&lt;br /&gt;
    // Please refer to existing callbacks in core for examples.&lt;br /&gt;
&lt;br /&gt;
    // ...&lt;br /&gt;
&lt;br /&gt;
    // Use core_tag_index_builder to build and filter the list of items. &lt;br /&gt;
    // Notice how we search for 6 items when we need to display 5 - this way we will know that we need to display a link to the next page.&lt;br /&gt;
    $builder = new core_tag_index_builder(&#039;mod_wiki&#039;, &#039;wiki_pages&#039;, $query, $params, $page * $perpage, $perpage + 1);&lt;br /&gt;
&lt;br /&gt;
    // ...&lt;br /&gt;
&lt;br /&gt;
    $items = $builder-&amp;gt;get_items();&lt;br /&gt;
    if (count($items) &amp;gt; $perpage) {&lt;br /&gt;
        $totalpages = $page + 2; // We don&#039;t need exact page count, just indicate that the next page exists.&lt;br /&gt;
        array_pop($items);&lt;br /&gt;
    }&lt;br /&gt;
&lt;br /&gt;
    // Build the display contents.&lt;br /&gt;
    if ($items) {&lt;br /&gt;
        $tagfeed = new core_tag\output\tagfeed();&lt;br /&gt;
        foreach ($items as $item) {&lt;br /&gt;
            $tagfeed-&amp;gt;add(...);&lt;br /&gt;
        }&lt;br /&gt;
&lt;br /&gt;
        $content = $OUTPUT-&amp;gt;render_from_template(&#039;core_tag/tagfeed&#039;, $tagfeed-&amp;gt;export_for_template($OUTPUT));&lt;br /&gt;
&lt;br /&gt;
        return new core_tag\output\tagindex($tag, &#039;mod_wiki&#039;, &#039;wiki_pages&#039;, $content,&lt;br /&gt;
                $exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===User-specific tags===&lt;br /&gt;
&lt;br /&gt;
It is possible that each tagged item can be tagged by each user independently. Before Moodle 3.0 this was how courses were tagged however from 3.0 tagging courses became more standard. The functionality remains in the API (argument $tiuser to the tagging functions).  In this case both tag list and tag cloud will display all tag instances added by all users but each user will be able to edit only their own.&lt;br /&gt;
&lt;br /&gt;
If developer chooses to implement it in the plugin, they need to also implement the UI when admin or other privileged user can remove or edit the instances of another user. Otherwise if teacher has tagged the course and later resigned there will be no way to change their tags. Also such tag instances need special treatment during backup and restore - they are now considered &amp;quot;user data&amp;quot; and user id mapping should be performed.&lt;br /&gt;
&lt;br /&gt;
===Advanced usages===&lt;br /&gt;
&lt;br /&gt;
Custom plugins may go beyond the standard tags handling and use them without mixing with regular course/user/wiki/blogs tags, hide them from the &amp;quot;Tag search&amp;quot; page and &amp;quot;Tags&amp;quot; block but instead have their own interface to search/categorise using tags. This can be achieved by defining tag collection, make it not searchable and specify a custom URL to link to when the tag is actually displayed. This all can be defined in db/tag.php, see the comments in [https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;tag_area::get_collection($component, $itemtype)&#039;&#039;&#039; - will return you the collection that your tag area is in&lt;br /&gt;
* &#039;&#039;&#039;tag_collection::get_tag_cloud()&#039;&#039;&#039; - will return all tags in the collection. There are no API methods to get the tags used in the tag area - this is actually the purpose of tag collections.&lt;br /&gt;
&lt;br /&gt;
==See also==&lt;br /&gt;
&lt;br /&gt;
* [[Core APIs]]&lt;br /&gt;
* [[Tag API before 3.1]]&lt;br /&gt;
* [https://docs.moodle.org/en/Managing_tags Managing tags]&lt;br /&gt;
&lt;br /&gt;
[[Category:API]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&amp;diff=56462</id>
		<title>lib/formslib.php Form Definition</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&amp;diff=56462"/>
		<updated>2019-09-23T13:48:15Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Formslib}}&lt;br /&gt;
== &#039;&#039;definition()&#039;&#039; ==&lt;br /&gt;
&lt;br /&gt;
The definition of the elements to be included in the form, their &#039;types&#039; (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;definition()&#039;&#039; is used to define the elements in the form and &#039;&#039;&#039;this definition will be used for validating data submitted as well as for printing the form.&#039;&#039;&#039; For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.&lt;br /&gt;
&lt;br /&gt;
The &#039;&#039;definition()&#039;&#039; should include all elements that are going to be used on form, some elements may be removed or tweaked later in &#039;&#039;definition_after_data()&#039;&#039;. Please do not create conditional elements in &#039;&#039;definition()&#039;&#039;, the definition() should not directly depend on the submitted data.&lt;br /&gt;
&lt;br /&gt;
Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods. &lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
require_once(&amp;quot;$CFG-&amp;gt;libdir/formslib.php&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
class simplehtml_form extends moodleform {&lt;br /&gt;
&lt;br /&gt;
    function definition() {&lt;br /&gt;
        global $CFG;&lt;br /&gt;
       &lt;br /&gt;
        $mform = $this-&amp;gt;_form; // Don&#039;t forget the underscore! &lt;br /&gt;
&lt;br /&gt;
        $mform-&amp;gt;addElement()... // Add elements to your form&lt;br /&gt;
            ...&lt;br /&gt;
    }                           // Close the function&lt;br /&gt;
}                               // Close the class&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
===Passing parameters to the Form===&lt;br /&gt;
&lt;br /&gt;
The constructor for &#039;&#039;moodleform&#039;&#039; allows a number of parameters including one (&#039;&#039;$customdata&#039;&#039;) to permit an array of arbitrary data to be passed to your form. &lt;br /&gt;
&lt;br /&gt;
For example, you can pass the data &amp;quot;$email&amp;quot; and &amp;quot;$username&amp;quot; to the Form&#039;s class for use inside (say) the definition.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
 $mform_simple = new simplehtml_form( null, array(&#039;email&#039;=&amp;gt;$email, &#039;username&#039;=&amp;gt;$username ) );&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
(the first parameter is $action, &#039;&#039;null&#039;&#039; will cause the form action to be determined automatically)&lt;br /&gt;
&lt;br /&gt;
Secondly, inside the form definition you can use those parameters to set the default values to some of the form&#039;s fields&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
 $mform-&amp;gt;addElement(&#039;text&#039;, &#039;email&#039;, get_string(&#039;email&#039;), &#039;maxlength=&amp;quot;100&amp;quot; size=&amp;quot;25&amp;quot; &#039;);&lt;br /&gt;
 $mform-&amp;gt;setType(&#039;email&#039;, PARAM_NOTAGS);&lt;br /&gt;
 $mform-&amp;gt;addRule(&#039;email&#039;, get_string(&#039;missingemail&#039;), &#039;required&#039;, null, &#039;server&#039;);&lt;br /&gt;
 // Set default value by using a passed parameter&lt;br /&gt;
 $mform-&amp;gt;setDefault(&#039;email&#039;,$this-&amp;gt;_customdata[&#039;email&#039;]);&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Use Fieldsets to group Form Elements==&lt;br /&gt;
&lt;br /&gt;
You use code like this to open a fieldset with a &#039;&#039;legend&#039;&#039;. &amp;lt;br /&amp;gt;&lt;br /&gt;
(&#039;&#039;&#039;Note&#039;&#039;&#039;: Some themes turn off legends on admin setting pages by using CSS: &amp;lt;nowiki&amp;gt;#adminsettings legend {display:none;}&amp;lt;/nowiki&amp;gt;.)&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;header&#039;, &#039;nameforyourheaderelement&#039;, get_string(&#039;titleforlegened&#039;, &#039;modulename&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can&#039;t yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.&lt;br /&gt;
&lt;br /&gt;
{{Moodle 2.5}}&lt;br /&gt;
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
 $mform-&amp;gt;setExpanded(&#039;foo&#039;)&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You close a fieldset with moodle_form&#039;s closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;closeHeaderBefore(&#039;buttonar&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==addElement==&lt;br /&gt;
&lt;br /&gt;
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.&lt;br /&gt;
&lt;br /&gt;
Some examples are below :&lt;br /&gt;
=== button ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;button&#039;, &#039;intro&#039;, get_string(&amp;quot;buttonlabel&amp;quot;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A button element. If you want a submit or cancel button see &#039;submit&#039; element.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=== autocomplete ===&lt;br /&gt;
{{Moodle 3.1}}&lt;br /&gt;
Available since Moodle 3.1&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$searchareas = \core_search\manager::get_search_areas_list(true);                                                           &lt;br /&gt;
$areanames = array();                                                                                                       &lt;br /&gt;
foreach ($searchareas as $areaid =&amp;gt; $searcharea) {                                                                          &lt;br /&gt;
    $areanames[$areaid] = $searcharea-&amp;gt;get_visible_name();                                                                  &lt;br /&gt;
}                                                                                                                           &lt;br /&gt;
$options = array(                                                                                                           &lt;br /&gt;
    &#039;multiple&#039; =&amp;gt; true,                                                  &lt;br /&gt;
&lt;br /&gt;
                                                   &lt;br /&gt;
    &#039;noselectionstring&#039; =&amp;gt; get_string(&#039;allareas&#039;, &#039;search&#039;),                                                                &lt;br /&gt;
);         &lt;br /&gt;
$mform-&amp;gt;addElement(&#039;autocomplete&#039;, &#039;areaids&#039;, get_string(&#039;searcharea&#039;, &#039;search&#039;), $areanames, $options);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The autocomplete element is an advanced form element that supports server-side searching - or simple filtering of a predefined list of options. Some benefits of using this form element are that it handles very large datasets extremely well - it has great accessibility built in - and it gives a good user experience. If you have so much data you need to build pagination into a page - you could probably come up with a better design using this. The simplest way to use it is compatible with the standard &#039;select&#039; form element. You give it a list of options and some parameters to configure how it behaves. The valid parameters for this simple mode of operation are:&lt;br /&gt;
* multiple (boolean - default false) - Allow more than one selected item. The data coming from the form will be an array in this case.&lt;br /&gt;
&lt;br /&gt;
[[image:autocomplete_multiple2.png|center|thumb|alt=autocomplete with multiple option|autocomplete with multiple option.]]&lt;br /&gt;
&lt;br /&gt;
* noselectionstring (string - default &amp;lt;nowiki&amp;gt;&#039;&#039;&amp;lt;/nowiki&amp;gt;) - The text to display when nothing is selected.&lt;br /&gt;
* showsuggestions (boolean - default true) - Do not show the list of suggestions when the user starts typing.&lt;br /&gt;
* placeholder (string - default &amp;lt;nowiki&amp;gt;&#039;&#039;&amp;lt;/nowiki&amp;gt;) - The text to show in the search box when it is empty.&lt;br /&gt;
* casesensitive (boolean - default false) - Is the search case sensitive ?&lt;br /&gt;
* tags (boolean - default false) - This changes the behaviour so that the user can create new valid entries in the list by typing them and pressing enter.&lt;br /&gt;
* ajax (string - default &amp;lt;nowiki&amp;gt;&#039;&#039;&amp;lt;/nowiki&amp;gt;) - This string is the name of an AMD module that can fetch and format results.&lt;br /&gt;
&lt;br /&gt;
More explanation on the &#039;ajax&#039; option. This should be the name of an AMD module that implements 2 functions:&lt;br /&gt;
&amp;lt;code javascript&amp;gt;&lt;br /&gt;
/**                                                                                                                         &lt;br /&gt;
 * Source of data for Ajax element.                                                                                         &lt;br /&gt;
 *                                                                                                                          &lt;br /&gt;
 * @param {String} selector The selector of the auto complete element.                                                      &lt;br /&gt;
 * @param {String} query The query string.                                                                                  &lt;br /&gt;
 * @param {Function} callback A callback function receiving an array of results.                                            &lt;br /&gt;
 * @return {Void}                                                                                                           &lt;br /&gt;
*/                                                                                                                         &lt;br /&gt;
transport: function(selector, query, callback) ...&lt;br /&gt;
&lt;br /&gt;
/**                                                                                                                         &lt;br /&gt;
 * Process the results for auto complete elements.                                                                          &lt;br /&gt;
 *                                                                                                                          &lt;br /&gt;
 * @param {String} selector The selector of the auto complete element.                                                      &lt;br /&gt;
 * @param {Array} results An array or results.                                                                              &lt;br /&gt;
 * @return {Array} New array of results.                                                                                    &lt;br /&gt;
 */                                                                                                                         &lt;br /&gt;
processResults: function(selector, results)...&lt;br /&gt;
&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
A good example is here: [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/amd/src/frameworks_datasource.js admin/tool/lp/amd/src/frameworks_datasource.js]&lt;br /&gt;
&lt;br /&gt;
When using the ajax option in an mform with validation etc - it is recommended to sub-class the php class &amp;quot;MoodleQuickForm_autocomplete&amp;quot; so that you can provide a list of name and&lt;br /&gt;
values to populate the form element if the form is re-displayed due to a validation error. An example is [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/classes/form/framework_autocomplete.php admin/tool/lp/classes/form/framework_autocomplete.php].&lt;br /&gt;
&lt;br /&gt;
We have provided several useful subclasses of this form element already that are simple to use (course and tags).&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt; &lt;br /&gt;
    // Course example.&lt;br /&gt;
    //  Valid options are:                                                                                     &lt;br /&gt;
    //                       &#039;multiple&#039; - boolean multi select                                                                      &lt;br /&gt;
    //                       &#039;exclude&#039; - array or int, list of course ids to never show                                             &lt;br /&gt;
    //                       &#039;requiredcapabilities&#039; - array of capabilities. Uses ANY to combine them.                              &lt;br /&gt;
    //                       &#039;limittoenrolled&#039; - boolean Limits to enrolled courses.                                                &lt;br /&gt;
    //                       &#039;includefrontpage&#039; - boolean Enables the frontpage to be selected.  &lt;br /&gt;
    $options = array(&#039;multiple&#039; =&amp;gt; true, &#039;includefrontpage&#039; =&amp;gt; true);                                                           &lt;br /&gt;
    $mform-&amp;gt;addElement(&#039;course&#039;, &#039;mappedcourses&#039;, get_string(&#039;courses&#039;), $options); &lt;br /&gt;
&lt;br /&gt;
    // Tags&lt;br /&gt;
    //  Valid options are:                                                                                     &lt;br /&gt;
    //                       &#039;showstandard&#039; - boolean One of the core_tag_tag constants to say which tags to display&lt;br /&gt;
    //                       &#039;component&#039; - string The component name and itemtype define the tag area&lt;br /&gt;
    //                       &#039;itemtype&#039; - string The component name and itemtype define the tag area&lt;br /&gt;
    $mform-&amp;gt;addElement(&#039;tags&#039;, &#039;interests&#039;, get_string(&#039;interestslist&#039;), array(&#039;itemtype&#039; =&amp;gt; &#039;user&#039;, &#039;component&#039; =&amp;gt; &#039;core&#039;));     &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== checkbox ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;checkbox&#039;, &#039;ratingtime&#039;, get_string(&#039;ratingtime&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.&lt;br /&gt;
&lt;br /&gt;
You can have a 5th parameter $attributes, as on other elements.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;BEWARE:&#039;&#039;&#039; Unchecked checkboxes return nothing at all (as if they didn&#039;t exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. &#039;Advcheckbox&#039; eliminates this problem. &lt;br /&gt;
&lt;br /&gt;
==== advcheckbox ====&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;advcheckbox&#039;, &#039;ratingtime&#039;, get_string(&#039;ratingtime&#039;, &#039;forum&#039;), &#039;Label displayed after checkbox&#039;, array(&#039;group&#039; =&amp;gt; 1), array(0, 1));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Similar to the checkbox above, but with some important improvements:&lt;br /&gt;
&lt;br /&gt;
# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the &amp;lt;input&amp;gt; element. However, a special value of &#039;group&#039; can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]&lt;br /&gt;
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.&lt;br /&gt;
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.&lt;br /&gt;
&lt;br /&gt;
=== choosecoursefile ===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;choosecoursefile&#039;, &#039;mediafile&#039;, get_string(&#039;mediafile&#039;, &#039;lesson&#039;), array(&#039;courseid&#039;=&amp;gt;$COURSE-&amp;gt;id));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Choose a file from the course files area. The fourth option is a list of options for the element. &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&#039;courseid&#039; =&amp;gt;null,  //if it is null (default then use global $COURSE&lt;br /&gt;
      &#039;height&#039;   =&amp;gt;500,   // height of the popup window&lt;br /&gt;
      &#039;width&#039;    =&amp;gt;750,   // width of the popup window&lt;br /&gt;
      &#039;options&#039;  =&amp;gt;&#039;none&#039;); //options string for the pop up window &lt;br /&gt;
                          //eg. &#039;menubar=0,location=0,scrollbars,resizable&#039;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like &lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;maxlength&#039; =&amp;gt; 255, &#039;size&#039; =&amp;gt; 48)&amp;lt;/code&amp;gt;&lt;br /&gt;
to control the maxlength / size of the text box (note size will default to 48 if not specified)&lt;br /&gt;
&lt;br /&gt;
Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the &#039;&#039;&#039;addGroupRule()&#039;&#039;&#039; method in this (complex) way:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;$mform-&amp;gt;addGroupRule(&#039;elementname&#039;, array(&#039;value&#039; =&amp;gt; array(array(list, of, rule, params, but, fieldname))));&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Where: &#039;&#039;&#039;&amp;quot;elementname&amp;quot;&#039;&#039;&#039; is the name of the choosecoursefile group element, &#039;&#039;&#039;&amp;quot;value&amp;quot;&#039;&#039;&#039; is the name of the text field within the group and the &#039;&#039;&#039;&amp;quot;list, of, addrule, params, but, fieldname&amp;quot;&#039;&#039;&#039; is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.&lt;br /&gt;
&lt;br /&gt;
For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one &amp;quot;choosecoursefile&amp;quot; element, and it controls the maximum length of the field (255) with this use of addGroupRule():&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;$mform-&amp;gt;addGroupRule(&#039;reference&#039;, array(&#039;value&#039; =&amp;gt; array(array(get_string(&#039;maximumchars&#039;, &#039;&#039;, 255), &#039;maxlength&#039;, 255, &#039;client&#039;))));&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== date_selector ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;date_selector&#039;, &#039;assesstimefinish&#039;, get_string(&#039;to&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;startyear&#039; =&amp;gt; 1970, &lt;br /&gt;
    &#039;stopyear&#039;  =&amp;gt; 2020,&lt;br /&gt;
    &#039;timezone&#039;  =&amp;gt; 99,&lt;br /&gt;
    &#039;optional&#039;  =&amp;gt; false&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.&lt;br /&gt;
&lt;br /&gt;
=== date_time_selector ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;date_time_selector&#039;, &#039;assesstimestart&#039;, get_string(&#039;from&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form-&amp;gt;get_data(); the fourth param here is an array of options. The defaults for the options are:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;startyear&#039; =&amp;gt; 1970, &lt;br /&gt;
    &#039;stopyear&#039;  =&amp;gt; 2020,&lt;br /&gt;
    &#039;timezone&#039;  =&amp;gt; 99,&lt;br /&gt;
    &#039;step&#039;      =&amp;gt; 5&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.&lt;br /&gt;
&lt;br /&gt;
===duration===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $mform-&amp;gt;addElement(&#039;duration&#039;, &#039;timelimit&#039;, get_string(&#039;timelimit&#039;, &#039;quiz&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.&lt;br /&gt;
&lt;br /&gt;
You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:&lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;optional&#039; =&amp;gt; true)&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like &lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;size&#039; =&amp;gt; 5)&amp;lt;/code&amp;gt;&lt;br /&gt;
to control the size of the text box.&lt;br /&gt;
&lt;br /&gt;
=== editor ===&lt;br /&gt;
&lt;br /&gt;
This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;editor&#039;, &#039;fieldname&#039;, get_string(&#039;labeltext&#039;, &#039;langfile&#039;));&lt;br /&gt;
$mform-&amp;gt;setType(&#039;fieldname&#039;, PARAM_RAW);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
NOTE: It won&#039;t work properly without the setType() as shown.&lt;br /&gt;
&lt;br /&gt;
If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].&lt;br /&gt;
&lt;br /&gt;
You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;subdirs&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;maxbytes&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;maxfiles&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;changeformat&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;context&#039;=&amp;gt;null,&lt;br /&gt;
    &#039;noclean&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;trusttext&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;enable_filemanagement&#039; =&amp;gt; true);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The option &#039;enable_filemanagement&#039; will display the file management button on true and remove it on false.&lt;br /&gt;
&lt;br /&gt;
To save the data if you don&#039;t care about files:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$formdata = $mform-&amp;gt;get_data();&lt;br /&gt;
$text     = $formdata-&amp;gt;fieldname[&#039;text&#039;];&lt;br /&gt;
$format   = $formdata-&amp;gt;fieldname[&#039;format&#039;];&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note: Because the text editor might be &amp;quot;Atto&amp;quot; (depending on user preferences) and Atto has an &amp;quot;autosave&amp;quot; feature - it requires that the combination of $PAGE-&amp;gt;url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.&lt;br /&gt;
&lt;br /&gt;
=== file ===&lt;br /&gt;
&lt;br /&gt;
File upload input box with browse button. In the form definition type&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;file&#039;, &#039;attachment&#039;, get_string(&#039;attachment&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
after form submission and validation use&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if ($data = $mform-&amp;gt;get_data()) {&lt;br /&gt;
      ...&lt;br /&gt;
    $mform-&amp;gt;save_files($destination_directory);&lt;br /&gt;
      ...&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If there is no requirement to save the file, you can read the file contents directly into a string as follows...&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
    $mform-&amp;gt;get_file_content(&#039;attachment&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you need advanced settings such as required file, different max upload size or name of uploaded file&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$this-&amp;gt;set_upload_manager(new upload_manager(&#039;attachment&#039;, true, false, $COURSE, false, 0, true, true, false));&lt;br /&gt;
            $mform-&amp;gt;addElement(&#039;file&#039;, &#039;attachment&#039;, get_string(&#039;attachment&#039;, &#039;forum&#039;));&lt;br /&gt;
            $mform-&amp;gt;addRule(&#039;attachment&#039;, null, &#039;required&#039;);&lt;br /&gt;
&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if ($data = $mform-&amp;gt;get_data()) {&lt;br /&gt;
      ...&lt;br /&gt;
    $mform-&amp;gt;save_files($destination_directory);&lt;br /&gt;
    $newfilename = $mform-&amp;gt;get_new_filename();&lt;br /&gt;
      ...&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.&lt;br /&gt;
&lt;br /&gt;
Please note that if using set_upload_manager() it must be before addElement(&#039;file&#039;,..).&lt;br /&gt;
&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.&lt;br /&gt;
&lt;br /&gt;
===filepicker===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
General replacement of &#039;&#039;file&#039;&#039; element.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;filepicker&#039;, &#039;userfile&#039;, get_string(&#039;file&#039;), null, array(&#039;maxbytes&#039; =&amp;gt; $maxbytes, &#039;accepted_types&#039; =&amp;gt; &#039;*&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
See also [[Using the File API in Moodle forms]]&lt;br /&gt;
&lt;br /&gt;
=== hidden ===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;hidden&#039;, &#039;reply&#039;, &#039;yes&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A hidden element. Set the element name (in this case &#039;&#039;&#039;reply&#039;&#039;&#039;) to the stated value (in this case &#039;&#039;&#039;yes&#039;&#039;&#039;).&lt;br /&gt;
&lt;br /&gt;
=== html ===&lt;br /&gt;
You can add arbitrary HTML to your Moodle form:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;html&#039;, &#039;&amp;lt;div class=&amp;quot;qheader&amp;quot;&amp;gt;&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
See [http://moodle.org/mod/forum/discuss.php?d=126935 &amp;quot;Question: Can I put a moodleform inside a table td?&amp;quot;] for a concrete example.&lt;br /&gt;
&lt;br /&gt;
=== htmleditor &amp;amp; format ===&lt;br /&gt;
&lt;br /&gt;
These elements are now deprecated. Please use the [[#editor|editor]] field type instead.&lt;br /&gt;
&lt;br /&gt;
===modgrade===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;modgrade&#039;, &#039;scale&#039;, get_string(&#039;grade&#039;), false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.&lt;br /&gt;
&lt;br /&gt;
A helpbutton is automatically added.&lt;br /&gt;
&lt;br /&gt;
===modvisible===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;modvisible&#039;, &#039;visible&#039;, get_string(&#039;visible&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
This is a custom element for selecting a grade visibility in an activity mod update form.&lt;br /&gt;
&lt;br /&gt;
===password===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;password&#039;, &#039;password&#039;, get_string(&#039;label&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A password element. Fourth param is an array or string of attributes.&lt;br /&gt;
&lt;br /&gt;
===passwordunmask===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;passwordunmask&#039;, &#039;password&#039;, get_string(&#039;label&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.&lt;br /&gt;
&lt;br /&gt;
=== radio ===&lt;br /&gt;
{{Moodle 2.3}}&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$radioarray=array();&lt;br /&gt;
$radioarray[] = $mform-&amp;gt;createElement(&#039;radio&#039;, &#039;yesno&#039;, &#039;&#039;, get_string(&#039;yes&#039;), 1, $attributes);&lt;br /&gt;
$radioarray[] = $mform-&amp;gt;createElement(&#039;radio&#039;, &#039;yesno&#039;, &#039;&#039;, get_string(&#039;no&#039;), 0, $attributes);&lt;br /&gt;
$mform-&amp;gt;addGroup($radioarray, &#039;radioar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it&#039;s own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.&lt;br /&gt;
&lt;br /&gt;
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.&lt;br /&gt;
&lt;br /&gt;
Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.&lt;br /&gt;
&lt;br /&gt;
==== setDefault ====&lt;br /&gt;
&lt;br /&gt;
To set the default for a radio button group as above use the following :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;yesno&#039;, 0);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This would make the default &#039;no&#039;.&lt;br /&gt;
&lt;br /&gt;
===select===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;type&#039;, get_string(&#039;forumtype&#039;, &#039;forum&#039;), $FORUM_TYPES, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.&lt;br /&gt;
&lt;br /&gt;
It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].&lt;br /&gt;
&lt;br /&gt;
You can set an &#039;onchange&#039; attribute when adding or creating the select element: &lt;br /&gt;
&lt;br /&gt;
$form-&amp;gt;addElement(&#039;select&#039;, &#039;iselTest&#039;, &#039;Test Select:&#039;, $arrayOfOptions, array(&#039;onchange&#039; =&amp;gt; &#039;javascript:myFunctionToDoSomething();&#039;));&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
====multi-select====&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$select = $mform-&amp;gt;addElement(&#039;select&#039;, &#039;colors&#039;, get_string(&#039;colors&#039;), array(&#039;red&#039;, &#039;blue&#039;, &#039;green&#039;), $attributes);&lt;br /&gt;
$select-&amp;gt;setMultiple(true);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=====setSelected=====&lt;br /&gt;
&lt;br /&gt;
To set the default selected item in a select element, you can use the &#039;setSelected&#039; method. The &#039;setSelected&#039; can either get a value or an array of values.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$options = array(&lt;br /&gt;
    &#039;ff0000&#039; =&amp;gt; &#039;Red&#039;,&lt;br /&gt;
    &#039;00ff00&#039; =&amp;gt; &#039;Green&#039;,&lt;br /&gt;
    &#039;0000ff&#039; =&amp;gt; &#039;Blue&#039;&lt;br /&gt;
);&lt;br /&gt;
$select = $mform-&amp;gt;addElement(&#039;select&#039;, &#039;colors&#039;, get_string(&#039;colors&#039;), $options);&lt;br /&gt;
// This will select the colour blue.&lt;br /&gt;
$select-&amp;gt;setSelected(&#039;0000ff&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Or for multiple-selection:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$skillsarray = array(&lt;br /&gt;
    &#039;val1&#039; =&amp;gt; &#039;Skill A&#039;,&lt;br /&gt;
    &#039;val2&#039; =&amp;gt; &#039;Skill B&#039;,&lt;br /&gt;
    &#039;val3&#039; =&amp;gt; &#039;Skill C&#039;&lt;br /&gt;
);&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;md_skills&#039;, get_string(&#039;skills&#039;, &#039;metadata&#039;), $skillsarray);&lt;br /&gt;
$mform-&amp;gt;getElement(&#039;md_skills&#039;)-&amp;gt;setMultiple(true);&lt;br /&gt;
// This will select the skills A and B.&lt;br /&gt;
$mform-&amp;gt;getElement(&#039;md_skills&#039;)-&amp;gt;setSelected(array(&#039;val1&#039;, &#039;val2&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
However you probably don&#039;t want to do this. Instead you probably want to use setDefault, or set it using the form&#039;s setData method.&lt;br /&gt;
&lt;br /&gt;
===selectyesno===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;selectyesno&#039;, &#039;maxbytes&#039;, get_string(&#039;maxattachmentsize&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.&lt;br /&gt;
&lt;br /&gt;
===selectwithlink===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$options = array();&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;selectwithlink&#039;, &#039;scaleid&#039;, get_string(&#039;scale&#039;), $options, null, &lt;br /&gt;
    array(&#039;link&#039; =&amp;gt; $CFG-&amp;gt;wwwroot.&#039;/grade/edit/scale/edit.php?courseid=&#039;.$COURSE-&amp;gt;id, &#039;label&#039; =&amp;gt; get_string(&#039;scalescustomcreate&#039;)));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
select type element with options containing link&lt;br /&gt;
===static===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;static&#039;, &#039;description&#039;, get_string(&#039;description&#039;, &#039;exercise&#039;),&lt;br /&gt;
    get_string(&#039;descriptionofexercise&#039;, &#039;exercise&#039;, $COURSE-&amp;gt;students));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.&lt;br /&gt;
&lt;br /&gt;
===submit, reset and cancel===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
//normally you use add_action_buttons instead of this code&lt;br /&gt;
$buttonarray=array();&lt;br /&gt;
$buttonarray[] = $mform-&amp;gt;createElement(&#039;submit&#039;, &#039;submitbutton&#039;, get_string(&#039;savechanges&#039;));&lt;br /&gt;
$buttonarray[] = $mform-&amp;gt;createElement(&#039;reset&#039;, &#039;resetbutton&#039;, get_string(&#039;revert&#039;));&lt;br /&gt;
$buttonarray[] = $mform-&amp;gt;createElement(&#039;cancel&#039;);&lt;br /&gt;
$mform-&amp;gt;addGroup($buttonarray, &#039;buttonar&#039;, &#039;&#039;, &#039; &#039;, false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A &#039;Submit&#039; type element is a submit type form element which will submit the form. A &#039;Reset&#039; will not submit the form but will reset any changes the user has made to form contents. A &#039;Cancel&#039; element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.&lt;br /&gt;
&lt;br /&gt;
You should name your submit and reset buttons &#039;submitbutton&#039; and &#039;resetbutton&#039; or something similar (not &#039;submit&#039; and &#039;reset&#039;). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.&lt;br /&gt;
&lt;br /&gt;
====add_action_buttons($cancel = true, $submitlabel=null);====&lt;br /&gt;
&lt;br /&gt;
You will normally use this helper function which is a method of moodleform to add all the &#039;action&#039; buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string(&#039;savechanges&#039;). Note the &#039;&#039;&#039;$this&#039;&#039;&#039; not &#039;&#039;&#039;$mform&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$this-&amp;gt;add_action_buttons();&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===text===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;text&#039;, &#039;name&#039;, get_string(&#039;forumname&#039;, &#039;forum&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
For a simple text input element. (For text labels, use the &#039;static&#039; element.)  Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$attributes=&#039;size=&amp;quot;20&amp;quot;&#039;;&lt;br /&gt;
$attributes=array(&#039;size&#039;=&amp;gt;&#039;20&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
 &lt;br /&gt;
Generally you are encouraged to use CSS instead of using attributes for styling.&lt;br /&gt;
&lt;br /&gt;
A format element can be used as a format select box. It will be non-selectable if you&#039;re using an html editor.&lt;br /&gt;
&lt;br /&gt;
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.&lt;br /&gt;
&lt;br /&gt;
====RTL support====&lt;br /&gt;
{{Moodle 3.2}}&lt;br /&gt;
&lt;br /&gt;
As of Moodle 3.2, some form elements have been refined to better support right-to-left languages. In RTL, most fields should not have their direction flipped, a URL, a path to a file, a number, ... are always displayed LTR. Input fields and text areas now will best guess whether they should be forced to be displayed in LTR based on the PARAM type associated with it. You can call:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;setForceLtr(&#039;name&#039;, true/false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
on some form fields (like &#039;text&#039;) to manually set the value, and for directionality.&lt;br /&gt;
&lt;br /&gt;
====float====&lt;br /&gt;
{{Moodle 3.7}}&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;float&#039;, &#039;defaultmark&#039;, get_string(&#039;defaultmark&#039;, &#039;question&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
Use the float element if you want a text box to get a floating point number. This element automatically supports localised decimal separators. You don&#039;t need to use setType with the float element.&lt;br /&gt;
&lt;br /&gt;
===textarea===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;textarea&#039;, &#039;introduction&#039;, get_string(&amp;quot;introtext&amp;quot;, &amp;quot;survey&amp;quot;), &#039;wrap=&amp;quot;virtual&amp;quot; rows=&amp;quot;20&amp;quot; cols=&amp;quot;50&amp;quot;&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.&lt;br /&gt;
&lt;br /&gt;
===recaptcha===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;recaptcha&#039;, &#039;recaptcha_field_name&#039;, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.&lt;br /&gt;
&lt;br /&gt;
To check whether recaptcha is enabled at site level use:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
if (!empty($CFG-&amp;gt;recaptchapublickey) &amp;amp;&amp;amp; !empty($CFG-&amp;gt;recaptchaprivatekey)) {&lt;br /&gt;
    //recaptcha is enabled&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===tags===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;tags&#039;, &#039;field_name&#039;, $lable, $options, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Used for editing a list of tags, for example on a blog post.&lt;br /&gt;
&lt;br /&gt;
There is only one option available, &#039;display&#039;, which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.&lt;br /&gt;
&lt;br /&gt;
The value should be set/returned as an array of tags.&lt;br /&gt;
&lt;br /&gt;
===grading===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;grading&#039;, &#039;advancedgrading&#039;, get_string(&#039;grade&#039;).&#039;:&#039;, array(&#039;gradinginstance&#039; =&amp;gt; $gradinginstance));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Custom element for advanced grading plugins.&lt;br /&gt;
&lt;br /&gt;
When adding the &#039;grading&#039; element to the form, developer must pass an object of class gradingform_instance as $attributes[&#039;gradinginstance&#039;]. Otherwise an exception will be thrown.&lt;br /&gt;
&lt;br /&gt;
===questioncategory===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;questioncategory&#039;, &#039;category&#039;, get_string(&#039;category&#039;, &#039;question&#039;),&lt;br /&gt;
    array(&#039;contexts&#039;=&amp;gt;$contexts, &#039;top&#039;=&amp;gt;true, &#039;currentcat&#039;=&amp;gt;$currentcat, &#039;nochildrenof&#039;=&amp;gt;$currentcat));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Creates a drop down element to select a question category.&lt;br /&gt;
&lt;br /&gt;
Options are:&lt;br /&gt;
&#039;&#039;&#039;contexts&#039;&#039;&#039; - (required) context in which question appears&lt;br /&gt;
&#039;&#039;&#039;currentcat&#039;&#039;&#039; - (optional) course category&lt;br /&gt;
&#039;&#039;&#039;top&#039;&#039;&#039; - (optional) if true will put top categories on top&lt;br /&gt;
&#039;&#039;&#039;nochildrenof&#039;&#039;&#039; - (optional) Format categories into an indented list reflecting the tree structure&lt;br /&gt;
&lt;br /&gt;
=== filetypes ===&lt;br /&gt;
{{Moodle 3.4}}&lt;br /&gt;
Available since Moodle 3.4&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;filetypes&#039;, &#039;allowedfiletypes&#039;, get_string(&#039;allowedfiletypes&#039;, &#039;tool_myplugin&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Creates  an input element allowing the user to specify file types for the given purpose. The typical scenario is a setting that allows the teacher define a list of allowed file types submitted by students.&lt;br /&gt;
&lt;br /&gt;
The element allows the user to either type the list of filetypes manually, or select the types from the list. Also supported is selecting the whole group of file types - such as &amp;quot;image&amp;quot;. The element integrates with the [[Core filetypes]] system so all default types and groups are presented, as well as those [[:en:Working with files#Site administration settings|defined locally by the admin]].&lt;br /&gt;
&lt;br /&gt;
As the list can be types in manually, the form processing code should always normalize it first via the provided utility methods:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$formdata = $mform-&amp;gt;get_data();&lt;br /&gt;
$filetypesutil = new \core_form\filetypes_util();&lt;br /&gt;
$allowedfiletypes = $filetypesutil-&amp;gt;normalize_file_types($formdata-&amp;gt;allowedfiletypes);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This always returns an array of recognized valid values. The original list can be separated by whitespace, end of lines, commas, colons and semicolons. During the normalization, values are converted to lowercase, empty valies and duplicates are removed. Glob evaluation is not supported.&lt;br /&gt;
&lt;br /&gt;
The normalization should also happen if the previously defined list had been saved to the database and re-read for actual usage. The normalization output value can be directly used as the accepted_types option for the filepicker.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$filetypesutil = new \core_form\filetypes_util();&lt;br /&gt;
$options[&#039;accepted_types&#039;] = $filetypesutil-&amp;gt;normalize_file_types($allowedfiletypes);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
By default, user input is validated against the list of known file types and groups. This validation can be disabled via options.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Supported options&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
; onlytypes : Allow selection from these file types only; for example [&#039;onlytypes&#039; =&amp;gt; [&#039;web_image&#039;]].&lt;br /&gt;
; allowall : Allow to select &#039;All file types&#039;, defaults to true. Does not apply with onlytypes are set.&lt;br /&gt;
; allowunknown : Skip implicit validation against the list of known file types.&lt;br /&gt;
&lt;br /&gt;
Example:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;filetypes&#039;, &#039;doctypes&#039;, get_string(&#039;doctypes&#039;, &#039;tool_myplugin&#039;), [&#039;onlytypes&#039; =&amp;gt; [&#039;document&#039;], &#039;allowunknown&#039; =&amp;gt; true]);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==addGroup==&lt;br /&gt;
&lt;br /&gt;
A &#039;group&#039; in formslib is just a group of elements that will have a label and will be included on one line. &lt;br /&gt;
&lt;br /&gt;
For example typical code to include a submit and cancel button on the same line : &lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$buttonarray=array();&lt;br /&gt;
$buttonarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;submit&#039;, &#039;submitbutton&#039;, get_string(&#039;savechanges&#039;));&lt;br /&gt;
$buttonarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;submit&#039;, &#039;cancel&#039;, get_string(&#039;cancel&#039;));&lt;br /&gt;
$mform-&amp;gt;addGroup($buttonarray, &#039;buttonar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).&lt;br /&gt;
&lt;br /&gt;
Here&#039;s a bad example (don&#039;t do this for real, use the &#039;optional&#039; =&amp;gt; true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name &#039;availablefromgroup&#039; but it doesn&#039;t disable the controlling element the &#039;availablefromenabled&#039; checkbox:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$availablefromgroup=array();&lt;br /&gt;
$availablefromgroup[] =&amp;amp; $mform-&amp;gt;createElement(&#039;date_selector&#039;, &#039;availablefrom&#039;, &#039;&#039;);&lt;br /&gt;
$availablefromgroup[] =&amp;amp; $mform-&amp;gt;createElement(&#039;checkbox&#039;, &#039;availablefromenabled&#039;, &#039;&#039;, get_string(&#039;enable&#039;));&lt;br /&gt;
$mform-&amp;gt;addGroup($availablefromgroup, &#039;availablefromgroup&#039;, get_string(&#039;availablefromdate&#039;, &#039;data&#039;), &#039;&amp;amp;nbsp;&#039;, false);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;availablefromgroup&#039;, &#039;availablefromenabled&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$group = $mform-&amp;gt;createElement(&#039;group&#039;, &#039;groupname&#039;, get_string(&#039;label&#039;), $groupitems);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$group = $mform-&amp;gt;createElement(&#039;group&#039;, &#039;groupname&#039;, get_string(&#039;label&#039;), $groupitems, null, false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==addRule==&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addRule(&#039;elementname&#039;, get_string(&#039;error&#039;), &#039;rule type&#039;, &#039;extraruledata&#039;, &#039;server&#039;(default), false, false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The first param(element) is an element name and second(message) is the error message that will be displayed to the user.&lt;br /&gt;
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
 * @param    string     $element       Form element name&lt;br /&gt;
 * @param    string     $message       Message to display for invalid data&lt;br /&gt;
 * @param    string     $type          Rule type, use getRegisteredRules() to get types&lt;br /&gt;
 * @param    string     $format        (optional)Required for extra rule data&lt;br /&gt;
 * @param    string     $validation    (optional)Where to perform validation: &amp;quot;server&amp;quot;, &amp;quot;client&amp;quot;&lt;br /&gt;
 * @param    boolean    $reset         Client-side validation: reset the form element to its original value if there is an error?&lt;br /&gt;
 * @param    boolean    $force         Force the rule to be applied, even if the target form element does not exist&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Common Rule Types&#039;&#039;&#039;&lt;br /&gt;
* required &lt;br /&gt;
* maxlength&lt;br /&gt;
* minlength&lt;br /&gt;
* rangelength&lt;br /&gt;
* email&lt;br /&gt;
* regex&lt;br /&gt;
* lettersonly&lt;br /&gt;
* alphanumeric&lt;br /&gt;
* numeric&lt;br /&gt;
* nopunctuation&lt;br /&gt;
* nonzero&lt;br /&gt;
* callback&lt;br /&gt;
* compare&lt;br /&gt;
&lt;br /&gt;
===Server side and Client side===&lt;br /&gt;
In case you use the &#039;&#039;Client side&#039;&#039; validation option, you can mainly check for an empty or not input field. unless you write some &#039;&#039;Client side&#039;&#039; code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.&lt;br /&gt;
In case you need a more complex validation checks which relay on Moodle&#039;s internal PHP libraries (or other/external PHP libraries) you better use the &#039;&#039;Server side&#039;&#039; validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client&#039;s side.&lt;br /&gt;
&lt;br /&gt;
==addHelpButton==&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addHelpButton(&#039;api_key_field&#039;, &#039;api_key&#039;, &#039;block_extsearch&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The following parameters are expected:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
 * @param $elementname The name of the form element to add the help button for&lt;br /&gt;
 * @param $identifier The identifier for the help string and its title (see below)&lt;br /&gt;
 * @param $component The component name to look for the help string in&lt;br /&gt;
 */&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
# get_string($identifier, $component) // The title of the help page&lt;br /&gt;
# get_string(&amp;quot;{$identifier}_help&amp;quot;, $component) // The content of the help page&lt;br /&gt;
&lt;br /&gt;
So you will need to have &#039;&#039;&#039;$identifier&#039;&#039;&#039; and &#039;&#039;&#039;{$identifier}_help&#039;&#039;&#039; defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers. &lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addHelpButton(&#039;shuffleanswers&#039;, &#039;shuffleanswers&#039;, &#039;qtype_multichoice&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
and so the language file includes the strings&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;shuffleanswers&#039;] = &#039;Shuffle the choices?&#039;; &lt;br /&gt;
$string[&#039;shuffleanswers_help&#039;] = &#039;If enabled,.....&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
You can also add the language string like&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;shuffleanswers_link&#039;] = &#039;question/shuffleanswers&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.&lt;br /&gt;
&lt;br /&gt;
==setDefault==&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;grade&#039;, get_string(&#039;gradeforsubmission&#039;, &#039;exercise&#039;), $grades);&lt;br /&gt;
$mform-&amp;gt;setHelpButton(&#039;grade&#039;, array(&#039;grade&#039;, get_string(&#039;gradeforsubmission&#039;, &#039;exercise&#039;), &#039;exercise&#039;));&lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;grade&#039;, 100);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an &#039;add&#039; rather than &#039;update&#039; function.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;editor&#039;, &#039;desc&#039;, get_string(&#039;description&#039;));     &lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;desc&#039;, array(&#039;text&#039;=&amp;gt;$defaulttext));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that when setting the default for an editor element you must use an array to define the default &amp;quot;text&amp;quot; value as shown above.&lt;br /&gt;
&lt;br /&gt;
==disabledIf==&lt;br /&gt;
&lt;br /&gt;
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.&lt;br /&gt;
&lt;br /&gt;
You can use $mform-&amp;gt;disabledIf($elementName, $dependentOn, $condition = &#039;notchecked&#039;, $value=&#039;1&#039;)&lt;br /&gt;
&lt;br /&gt;
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you&#039;ve used as the second argument in addElement or addGroup.&lt;br /&gt;
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you&#039;re adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.&lt;br /&gt;
* $condition will be &#039;notchecked&#039;, &#039;checked&#039;, &#039;noitemselected&#039;, &#039;eq&#039;, &#039;in&#039; or, if it is anything else, we test for &#039;neq&#039;.&lt;br /&gt;
** If $condition is &#039;eq&#039; or &#039;neq&#039; then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js&lt;br /&gt;
** If $condition is &#039;checked&#039; or &#039;notchecked&#039; then we check to see if a checkbox is checked or not.&lt;br /&gt;
** If $condition is &#039;in&#039; then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)&lt;br /&gt;
** If $condition is &#039;noitemselected&#039; then we check to see whether nothing is selected in a dropdown list.&lt;br /&gt;
&lt;br /&gt;
Examples:&lt;br /&gt;
 // Disable my control unless a checkbox is checked.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;somecheckbox&#039;);&lt;br /&gt;
 &lt;br /&gt;
 // Disable my control if a checkbox &#039;&#039;&#039;is&#039;&#039;&#039; checked.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;somecheckbox&#039;, &#039;checked&#039;);&lt;br /&gt;
 &lt;br /&gt;
 // Disable my control when a dropdown has value 42.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;someselect&#039;, &#039;eq&#039;, 42);&lt;br /&gt;
&lt;br /&gt;
 // Disable my control unless a dropdown has value 42.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;someselect&#039;, &#039;neq&#039;, 42);&lt;br /&gt;
&lt;br /&gt;
The possible choices here are in the dependency manager in lib/form/form.js.&lt;br /&gt;
===A tricky case===&lt;br /&gt;
&lt;br /&gt;
You need to take care with disabledIf if you plan to use it with groups of checkboxes.&lt;br /&gt;
&lt;br /&gt;
Let&#039;s say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.&lt;br /&gt;
&lt;br /&gt;
To fix ideas:&lt;br /&gt;
&lt;br /&gt;
If the selection in the checkboxes group is:&lt;br /&gt;
&lt;br /&gt;
 mycheck_01 == 1&lt;br /&gt;
 mycheck_02 == 0&lt;br /&gt;
 mycheck_03 == 0&lt;br /&gt;
 mycheck_04 == 0&lt;br /&gt;
 mycheck_05 == 1&lt;br /&gt;
&lt;br /&gt;
the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.&lt;br /&gt;
&lt;br /&gt;
The following code will, apparently, fail:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_01&#039;, &#039;neq&#039;, &#039;1&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_02&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_03&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_04&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_05&#039;, &#039;neq&#039;, &#039;1&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.&lt;br /&gt;
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element &amp;quot;mycheck_01&amp;quot; and will not apply the corresponding rule.&lt;br /&gt;
&lt;br /&gt;
A working solution for this kind of issue seems to be:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_01&#039;, &#039;notchecked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_02&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_03&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_04&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_05&#039;, &#039;notchecked&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.&lt;br /&gt;
&lt;br /&gt;
==hideIf==&lt;br /&gt;
{{Moodle 3.4}}&lt;br /&gt;
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.&lt;br /&gt;
This uses the same syntax as disabledIf just with hideIf instead.&lt;br /&gt;
&lt;br /&gt;
==setType==&lt;br /&gt;
&lt;br /&gt;
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).&lt;br /&gt;
&lt;br /&gt;
===Most Commonly Used PARAM_* Types===&lt;br /&gt;
&lt;br /&gt;
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.&lt;br /&gt;
&lt;br /&gt;
* PARAM_CLEAN is deprecated and you should try to use a more specific type.&lt;br /&gt;
* PARAM_TEXT should be used for cleaning data that is expected to contain multi-lang content. It will strip all html tags. But will still let tags for multilang support through.&lt;br /&gt;
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.&lt;br /&gt;
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().&lt;br /&gt;
* PARAM_INT should be used for integers. PARAM_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.&lt;br /&gt;
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.&lt;br /&gt;
&lt;br /&gt;
==disable_form_change_checker==&lt;br /&gt;
&lt;br /&gt;
By default, any Moodle form will pop-up an &amp;quot;Are you sure?&amp;quot; alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call&lt;br /&gt;
&lt;br /&gt;
 $mform-&amp;gt;disable_form_change_checker()&lt;br /&gt;
&lt;br /&gt;
==References==&lt;br /&gt;
&lt;br /&gt;
* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com&lt;br /&gt;
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]&lt;br /&gt;
&lt;br /&gt;
[[Category:Formslib]]&lt;br /&gt;
[[Category:Interfaces]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=56396</id>
		<title>Integration Review</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Integration_Review&amp;diff=56396"/>
		<updated>2019-09-05T15:11:32Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* Process for requesting a non bug-fix backport */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;==Purpose==&lt;br /&gt;
&lt;br /&gt;
The purpose of the integration review is to:&lt;br /&gt;
* Ensure consistent quality across the codebase&lt;br /&gt;
* Ensure that pedagogical aims of Moodle are at the forefront of any change&lt;br /&gt;
* Take into consideration the holistic view of moodle, looking at the impact beyond where the original developer was focused&lt;br /&gt;
* Provide guidance and feedback to developers, helping them learn and improve &lt;br /&gt;
* Consider &#039;&#039;&#039;other perspectives&#039;&#039;&#039; of other users perhaps not considered by original developers e.g.&lt;br /&gt;
** Teachers&lt;br /&gt;
** Students&lt;br /&gt;
** Administrators&lt;br /&gt;
**Third-party developers&lt;br /&gt;
&lt;br /&gt;
==Integration Review Process==&lt;br /&gt;
&lt;br /&gt;
# Run automated pre-checks against the continuous integration server. (In future this can be automated and also moved into a publicly accessible domain.)&lt;br /&gt;
# Final code review, much like the peer review, except that this is the final check. To include&lt;br /&gt;
## Takes place in-situ (integrated) to examine the impact to other integrated issues&lt;br /&gt;
## Checking against the coding guidelines - syntax/whitespace&lt;br /&gt;
## Moodleisms - using the built-in API functions where appropriate&lt;br /&gt;
## Cross-DB compatibility &lt;br /&gt;
## Security&lt;br /&gt;
# Check purpose - the patch needs to fix the issue reported.&lt;br /&gt;
# Verify target branches are appropriated. They must match 100% the rules defined for [[#Backporting|backporting issues]].&lt;br /&gt;
# Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:&lt;br /&gt;
## Well discussed with evidence of justification&lt;br /&gt;
## Documented and communicated to the community &lt;br /&gt;
# Verify that components are correct and check the right people have been involved (e.g. component maintainers)&lt;br /&gt;
# For fundamental changes, check that a thread has been started in an appropriate forum, and other Moodlers, given enough time to comment.&lt;br /&gt;
# Tests - must be written to guide tester to verify the fix is working.&lt;br /&gt;
## Unit test - very much preferred if applicable&lt;br /&gt;
## at end of Wednesday, ensure testing is going to complete as expected. else take other actions (speak to test manager)&lt;br /&gt;
# Performance - we have to look at maintaining optimum code here, as far as simple patches that can affect performance. (simple optimisations)&lt;br /&gt;
# Scalability - if master only - we&#039;re looking far future, stable branches may not be lucky to get such improvements.&lt;br /&gt;
# git authorship is correct vs committer + credits due are mentioned + email addresses&lt;br /&gt;
# Documentation / PHP Doc / readability&lt;br /&gt;
# [[Tracker issue labels]] which might need adding. Particularly:&lt;br /&gt;
## docs_required / dev_docs_required / release_notes: About which type of documentation is required for the issue.&lt;br /&gt;
## ui_change / api_change: About the implications of the change.&lt;br /&gt;
## unit_test_required / acceptance_test_required / qa_test_required: About the need to cover the issue with some test.&lt;br /&gt;
# [[Tracker issue versions]] review. Particularly:&lt;br /&gt;
## Fixed Version after integration - is the versions that the issue is patched for. (A rule here: [[Tracker issue versions#Some general and simple rules|&amp;quot;or stables or master&amp;quot;]]).&lt;br /&gt;
## Remove any &amp;quot;Must fix for X.Y&amp;quot; version once the issue is integrated.&lt;br /&gt;
# Assign the tester.&lt;br /&gt;
## Don&#039;t forget to update the weight in the testers sheet&lt;br /&gt;
&lt;br /&gt;
== Integration Principles ==&lt;br /&gt;
&lt;br /&gt;
Integration (non-technical but philosophical) principles (4-5 words determining if something has to be integrated/backported or no):&lt;br /&gt;
&lt;br /&gt;
# safety: if something does not look safe, stable, it won&#039;t land. Be conservative.&lt;br /&gt;
# security: all security issues, if not breaking principle (1) will be integrated/backported to all security-supported versions.&lt;br /&gt;
# community: Anything not useful for the community (or against it) won&#039;t be integrated/backported. We can measure the community as 10%HQ, 10%Partners, 10%Core developers, 20%Admins, 20%Teachers, 30%Students - not exact science, just one approximation, you know). Question yourself how the change will affect those groups and ensure positives are bigger always (only affected groups count). All community issues, if not breaking principles (1) and (2) will be integrated.&lt;br /&gt;
# typology:  bug fixes will be always integrated/backported to all the supported braches if none of the principles (1), (2) and (3) are violated. Also, partially-unsupported branches can receive some if they are important enough. Improvements and new features go, exclusively, to master only, that&#039;s the main reason for short release periods. We *must* not make exceptions to this.&lt;br /&gt;
# priority: issues will be &amp;quot;ordered down&amp;quot; by priority down (where priority is a [https://tracker.moodle.org/issues/?filter=14000 mix of various factors], dynamic). And will be integrated in that order. If something has to be delayed, better if it is low priority. Once again, nothing here can break any of the previous principles.&lt;br /&gt;
# tests: unit tests and acceptance tests will backported as much as possible without breaking (1) and (2). New features required to implement tests will be backported if the API is 100% backwards compatible. &lt;br /&gt;
If all the principles are fulfilled, the answer for &amp;quot;should I integrate this?&amp;quot; is, &amp;quot;yes, please!&amp;quot;&lt;br /&gt;
(apart from technical findings, of course, that can lead to the issue being not integrated/reopened at last, these principles are 100% philosophical)&lt;br /&gt;
&lt;br /&gt;
==Schedule==&lt;br /&gt;
===In normal periods ===&lt;br /&gt;
The integrators adhere to the following schedule:&lt;br /&gt;
&lt;br /&gt;
* Monday 07:00 (UTC+8) and 19:00 (UTC+8): Issues waiting for integration are brought into current integration automatically.&lt;br /&gt;
* Monday to Thursday until 12:00 (UTC+8): Integration and [[Testing of integrated issues#The testing process|Testing]] happen.&lt;br /&gt;
* Thursday after 12:00 (UTC+8): Integrators duties during this time are to monitor, facilitate and &#039;problem solve&#039; the testing process.&lt;br /&gt;
* Friday: Testing should be completed before (the sooner the better) 12:00 (UTC+8) at which time remaining testing failures will be reverted/rewritten and reopened. The release process follows.&lt;br /&gt;
* Friday after 12:00 (UTC+8):: Should be kept free from integration. Integration systems are maintained during this time.&lt;br /&gt;
&lt;br /&gt;
Note that under the strict schedule above, it is specially important &#039;&#039;&#039;to be as responsive as possible&#039;&#039;&#039;, both when the issue is being integrated and when [[Testing_of_integrated_issues#Expectation_from_tester|testing]]. Any significant delay by any of the actors involved will result in the issue being moved out from current integration.&lt;br /&gt;
&lt;br /&gt;
=== During continuous integration/Freeze/QA period ===&lt;br /&gt;
During the continuous integration period (last 6 weeks before release) the integration team are continuously focused on producing regular builds of master to facilitate QA and fast fixes to issues identified.&lt;br /&gt;
&lt;br /&gt;
* Throughout:&lt;br /&gt;
** Issues are picked on a one by one basis, prioritising [https://docs.moodle.org/dev/QA_testing#Resetting_tests QA blockers] and master regressions (MUST FIX) issues.&lt;br /&gt;
** After freeze (usually 5 weeks before release) any non bug fix issues are given the &#039;&#039;integration_held&#039;&#039; label and are explicitly not picked for integration. Still, anybody is able to add a reasoned &#039;&#039;unhold_requested&#039;&#039; label to those issues in order to get them unblocked by the development managers. Note this does not guarantee the issue to land before release, but just gives it a chance to be integrated like any other issue.&lt;br /&gt;
** Our goal is to achieve &#039;releaseability&#039; throughout, so we stop integrating to ensure a release happens&lt;br /&gt;
&lt;br /&gt;
So, basically, once under continuous integration, we do organize work as follows:&lt;br /&gt;
* Continuous officially begins. Everybody is on integration. Until end of on-sync period.&lt;br /&gt;
* Monday: Integration and [[Testing of integrated issues#Differences in test process during continuous integration periods|testing]] happens.&lt;br /&gt;
* Tuesday: Integration happens until 12:00 (UTC+8), [[Testing of integrated issues#Differences in test process during continuous integration periods|afterwards we try to achieve 100% &#039;Test Passed&#039;]] and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
* Wednesday: [Assuming a master release has been rolled] Integration and testing continues&lt;br /&gt;
* Thursday: Integration and testing continues&lt;br /&gt;
* Friday: Integration happens until 12:00 (UTC+8), afterwards we try to achieve 100% &#039;Test Passed&#039; and stop integrating any untested changes until a master release is produced.&lt;br /&gt;
&lt;br /&gt;
Note: along this period we always release as many stable weeklies, both supported (always) and security only (when there are changes), as master rolls (on-demand, beta, rc) happen (see MDLSITE-3470). Note that those tags are not simply tags but they come with some important implications, aiming to stability, safety and clarity. Integrators will try to remain loyal to them, be warned:&lt;br /&gt;
&lt;br /&gt;
* Once beta is released... new features or improvements &amp;quot;unrelated&amp;quot; with the release will be really harder to be accepted. A +4 from developer managers (normally +3 is enough) will be needed to proceed with the issue. Integrators vote will be, always, -1.&lt;br /&gt;
* Once rc are released... new features or improvements &amp;quot;unrelated&amp;quot; with the release are forbidden. No unhold voting, no managers. Simply forbidden.&lt;br /&gt;
* Last week before release, only &amp;quot;related&amp;quot; issues will be picked for integration. Everything else (bug fixes included) are kept out (given the &amp;quot;integration_held&amp;quot; label) if unrelated, at very least until after release. No distractions.&lt;br /&gt;
Definition: &amp;quot;related&amp;quot;: said to be a followup of required/planned to release OR a direct (and recent) regression caused by a bug fix OR a security issue.&lt;br /&gt;
&lt;br /&gt;
=== On-sync period ===&lt;br /&gt;
Immediately after a major release and for a short period (right now, 2 weeks, matching 1st HQ sprint duration), the integration team is under the named on-sync period.&lt;br /&gt;
&lt;br /&gt;
At all effects, it&#039;s a normal period (see above), and weeklies are produced for supported stable branches and also for master. But with one important rule/goal:&lt;br /&gt;
&lt;br /&gt;
* We must keep the latest stable branch and master 100% on-sync, specifically about versions and upgrade steps. Some well-known exceptions to this are: &#039;&#039;.travis.yml&#039;&#039;, &#039;&#039;backup.class.php&#039;&#039;, &#039;&#039;config.php&#039;&#039; (&#039;&#039;$release&#039;&#039;, &#039;&#039;$branch&#039;&#039;, &#039;&#039;$maturity&#039;&#039; and comments only, never &#039;&#039;$version&#039;&#039; !), &#039;&#039;install/lang/xx&#039;&#039; files (the new stable branch for install lang files is created 2w after the release).&lt;br /&gt;
&lt;br /&gt;
This simple, but important constraint, is there to facilitate the integration of impeding bugs, needing urgent resolution, and by keeping them the same, we guarantee that any stable or master fix will apply without problems to both branches. Of course, in order to achieve the rule, these must be also observed along the period:&lt;br /&gt;
&lt;br /&gt;
* We continuously perform diffs between the latest stable and master, controlling that we are on-sync. Any non-authorised difference is cleaned (rewritten). Whenever a latest stable branch is missing in the issue (it&#039;s optional over the period), we automatically cherry pick the changes straight from master.&lt;br /&gt;
* Both improvements and new features (and, in general, everything leading to divergence) are held until the on-sync period ends.&lt;br /&gt;
&lt;br /&gt;
Last, but not less important, a second goal for this on-sync period is:&lt;br /&gt;
&lt;br /&gt;
* The environmental requirements &#039;&#039;&#039;for next major version&#039;&#039;&#039; [[Release process#2_weeks_after|must be agreed and resolved so they can land to master]] early in the process, remaining defined and stable over the next, 6 months of, development cycle.&lt;br /&gt;
&lt;br /&gt;
As part of the standard [https://docs.moodle.org/dev/Release_process Moodle release process], at the beginning of the on-sync period, we &amp;quot;unhold&amp;quot; all bugs that were held during the last week before the release because they were unrelated to the release. At the end of the onsync period we &amp;quot;unhold&amp;quot; all new features that were submitted after the code freeze for the the release.&lt;br /&gt;
&lt;br /&gt;
== Backporting ==&lt;br /&gt;
&lt;br /&gt;
Whilst we&#039;d all like all Moodle users to be using our latest and greatest code, there is a balance to strike between improving our software and maintaining stability (both in terms of regressions, but also training and documentation materials). Large amounts of change on the stable branches make the lives difficult for institutions to manage upgrades between point releases.&lt;br /&gt;
&lt;br /&gt;
==== General policy ====&lt;br /&gt;
Our general policy is as follows:&lt;br /&gt;
&lt;br /&gt;
* Bug fixes will be backported to all (and only to) supported stable branches. &lt;br /&gt;
** When fixing a bug, please provide a fix for all supported stable branches. &lt;br /&gt;
** If a fix doesn&#039;t make sense to be backported to every branch, please make it clear in the issue.&lt;br /&gt;
* Improvements or new features will only land in master.&lt;br /&gt;
&lt;br /&gt;
==== Process for requesting a non bug-fix backport ====&lt;br /&gt;
Improvements or new features can be requested to be backported to the stable branches. We urge developers to consider this request carefully. In recent years, Moodle has moved to a short and predicatable time based release schedule and we use a very effective distributed source control system. Both of these process changes should ensure that a change not being backported to the stable branches is not as problematic as it may have used to be. &lt;br /&gt;
&lt;br /&gt;
Should you feel that a new feature or improvement needs backporting, please follow this process:&lt;br /&gt;
&lt;br /&gt;
# File a new issue.&lt;br /&gt;
# Set the issue title using our backport template guide.  (i.e. &amp;quot;Fix forum alignment (backport of MDL-99999)&amp;quot;) - see [https://docs.moodle.org/dev/Tracker_guide#Tracker_fields Tracker_guide]&lt;br /&gt;
# Link the original issue using link type &amp;quot;Will help resolve&amp;quot;.&lt;br /&gt;
# You should include clear rationale for the request to backport&lt;br /&gt;
&lt;br /&gt;
The integration team will process backport requests, with the following guidelines:&lt;br /&gt;
# The integration team will together consider each request individually considering the needs of the community (influenced by forum posts, moodle partners, nagging developers etc).&lt;br /&gt;
# Backports will happen not earlier than 3 weeks and not later than 2 months after the issue has landed in master.&lt;br /&gt;
# Rationale will be given for rejection&lt;br /&gt;
&lt;br /&gt;
If the backport request is approved, please follow the usual development process to submit the feature or improvement on earlier branches. Just to be clear, this means using the new bug number. So, even if the fix you are back-porting cherry-picks cleanly, you will need to amend the commit comment to use the new MDL-XXXXX number. It would be good practice to also add a line like &amp;quot;This is a backport of MDL-YYYYY.&amp;quot; in the amended commit comment. You can probably copy the testing instructions from the original issue. If so, make it clear you done this by saying something like &amp;quot;Copied from MDL-66327:&amp;quot;. Of course, if you can improve the instructions, feel free to edit. MDL-66614 and MDL-66327 are probably a reasonably good example fo what should be done.&lt;br /&gt;
&lt;br /&gt;
==== Polite note about bug classification ====&lt;br /&gt;
Many issues can be appropiately classified as borderline bugfix/improvements. We politely request that developers do not try and &#039;game the system&#039; by clasifying their improvements as bugs intentionally. If your fix is in a grey area, please state your case for it being a bug fix clearly. The integration team will use their discretion where necessary.&lt;br /&gt;
&lt;br /&gt;
==== Backport fixes to unsupported branches ====&lt;br /&gt;
* Given the [[#General policy|general policy]] above, only supported stable branches are candidates normally.&lt;br /&gt;
* Also security, privacy and dataloss issues are accepted to be fixed into security-only supported branches.&lt;br /&gt;
* Apart from the previous, issues required to keep the testing infrastructure working (travis, behat, phpunit...) will also be accepted when possible into security-only branches.&lt;br /&gt;
* Finally, backport to unsupported branches only will happen when the issue is a &#039;&#039;&#039;direct regression caused by a bug fix&#039;&#039;&#039; introduced by the latest releases. This applies to both security-only and out-of-support branches.&lt;br /&gt;
&lt;br /&gt;
A new weekly release will be performed including all the cases above, but  [[Process#Security issues|security issues that follow its own special process]] and are released bi-monthly.&lt;br /&gt;
&lt;br /&gt;
== Fixing issues identified during integration review/ testing ==&lt;br /&gt;
&lt;br /&gt;
When a branch has been merged by an integrator, it is important that you do not modify the existing history of your branch (e.g. by amending or squashing your commits) and instead add new commits on top. If you modify the history of your branch, it makes it extremely difficult for the integrator to merge your changes (and see the differences).&lt;br /&gt;
&lt;br /&gt;
As a general rule, this means that if your issue has entered the &#039;in integration review&#039; stage of the development process, please only add new commits on top of your existing commits. There are circumstances when your issue will be &#039;in integration review&#039; but not merged (and thus possible to squash changes) but if in any doubt, please add new commits and ask the integrator to squash your changes for you.&lt;br /&gt;
&lt;br /&gt;
== Commit squashing ==&lt;br /&gt;
&lt;br /&gt;
The Integration team will sometimes recommend squashing commits when things do not look natural (and may offer to do this for you), especially when there are &amp;quot;fix-commits&amp;quot; in the history happening before integration. But [https://moodle.org/local/chatlogs/index.php?conversationid=13987#c489485 our policy] is &amp;quot;if you want your history of commits to look like bad, it&#039;s your history&amp;quot;. You will not be forced to squash your changes. You should pay close attention to https://docs.moodle.org/dev/Coding_style#Git_commits and intend to  &amp;quot;Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
[[Category: Processes]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Setting_up_xhprof_on_Moodle&amp;diff=56353</id>
		<title>Setting up xhprof on Moodle</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Setting_up_xhprof_on_Moodle&amp;diff=56353"/>
		<updated>2019-09-02T15:34:44Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;The following instructions are for setting up tideways (the modern replacement for xhprof) for Moodle under a Ubuntu/Debian environment. The process should be similar for other linux enviroments, but will need some tweaking if you wish to do this under windows. Please update this document if you find any major problems.&lt;br /&gt;
&lt;br /&gt;
==Installing tideways with Linux==&lt;br /&gt;
&lt;br /&gt;
=== Tideways ===&lt;br /&gt;
&lt;br /&gt;
Latest version:&lt;br /&gt;
&lt;br /&gt;
sudo apt-get install php-tideways&lt;br /&gt;
&lt;br /&gt;
Older version&lt;br /&gt;
&lt;br /&gt;
 sudo apt-get install tideways-php&lt;br /&gt;
&lt;br /&gt;
===Build manually===&lt;br /&gt;
&lt;br /&gt;
There were outdated instructions here, you will need to follow the Tideways-supplied build instructions if you want do do this.&lt;br /&gt;
&lt;br /&gt;
===Troubleshooting===&lt;br /&gt;
&lt;br /&gt;
==== Graph isn&#039;t generated ====&lt;br /&gt;
&lt;br /&gt;
If you see a &#039;&#039;&#039;failed to shell execute cmd=&amp;quot; dot -Tpng&#039;&#039;&#039; error when you follow the &#039;&#039;&#039;View Full Callgraph&#039;&#039;&#039; link you may need to install graphviz:&lt;br /&gt;
&lt;br /&gt;
 sudo apt-get install graphviz&lt;br /&gt;
&lt;br /&gt;
Into Windows environment this error can be caused by a path hardcoded into &amp;quot;\lib\xhprof\xhprof_lib\utils\callgraph_utils.php&amp;quot;, you must replace one parameter of the proc_open function which is a Linux path &amp;quot;/tmp&amp;quot; by a Windows one, like &amp;quot;c:/temp&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
==== Call to undefined function tideways_enable ====&lt;br /&gt;
&lt;br /&gt;
Verion 5 of tideways was renamed which broke things:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
Exception - Call to undefined function tideways_enable()&lt;br /&gt;
Debug info: &lt;br /&gt;
Error code: generalexceptionmessage&lt;br /&gt;
Stack trace:&lt;br /&gt;
line 168 of /lib/xhprof/xhprof_moodle.php: Error thrown&lt;br /&gt;
line 819 of /lib/setup.php: call to profiling_start()&lt;br /&gt;
line 53 of /config.php: call to require_once()&lt;br /&gt;
line 37 of /my/index.php: call to require_once()&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
One solution is to update everything to the latest, or you can force downgrade tideways to v4:&lt;br /&gt;
&lt;br /&gt;
 sudo apt install tideways-php=4.1.6&lt;br /&gt;
&lt;br /&gt;
See also for more details&lt;br /&gt;
&lt;br /&gt;
https://tideways.com/profiler/blog/tideways-no-5&lt;br /&gt;
&lt;br /&gt;
https://tracker.moodle.org/browse/MDL-62280&lt;br /&gt;
&lt;br /&gt;
==Installing xhprof with Windows==&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;This section needs to be updated for Tideways/PHP 7&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
You will need to download PHP extensions compiled for your version of PHP. [http://dev.freshsite.pl/php-extensions/xhprof.html Here is one source...]&lt;br /&gt;
&lt;br /&gt;
Extract the contained dll file to the ext directory of your server. With XAMPP this is in xampp\php\ext&lt;br /&gt;
&lt;br /&gt;
Add a line to your php.ini file that matches dll filename you are using. This goes in the Dynamic Extensions section.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
extension=xhprof_0.10.3_php54_vc9.dll&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Stop and restart Apache through your server control interface. If it complains, you probably don&#039;t have the correct extension for your version of PHP, or the extension entry in your php.ini file doesn&#039;t match the dll file.&lt;br /&gt;
&lt;br /&gt;
To test that the extension is installed, log in to Moodle as an administrator and navigate to Administration &amp;gt; Site administration &amp;gt; Server &amp;gt; PHP info. Search for information about the xhprof extension. It should be present and enabled.&lt;br /&gt;
&lt;br /&gt;
==Configuring Moodle to use xhprof==&lt;br /&gt;
&lt;br /&gt;
[[Image:profilingOption.png|thumb|left|The profiling option is displayed when the php xhprof extension is installed]]&lt;br /&gt;
[[Image:profilingOutput.png|thumb|right|Tabular profiling output produced by xhprof]]&lt;br /&gt;
[[Image:callgraph.png|thumb|right|An example call graph showing slow parts of the profiled run]]&lt;br /&gt;
Once the xhprof php extension is correctly installed you will find a new &amp;quot;Profiling&amp;quot; option available under Settings &amp;gt; Site administration &amp;gt; Development&lt;br /&gt;
&lt;br /&gt;
When you load the profiling settings page you are confronted with several options. In order to get xhprof up and running with minimal fuss you merely need to check the &amp;quot;Enable profiling&amp;quot; box and set a path that you wish to be profiled. You can simply set this to a wildcard using the asterisk symbol (&#039;&#039;&#039;*&#039;&#039;&#039;) while you are testing profiling. Afterwards you can come back and set this to a more restrictive setting once you know profiling is working. Note the paths need to be specified relative to your Moodle directory and not the web root.&lt;br /&gt;
&lt;br /&gt;
After you have enabled profiling you should load some pages within the &amp;quot;Profile these&amp;quot; filter that you set in the step above. Once you have done these go to Settings &amp;gt; Site administration &amp;gt; Development &amp;gt; Profiling runs and you should see a list of the pages you visited. Clicking on one of these and then clicking on the &amp;quot;View profiling details&amp;quot; will take you to a profiling table full of helpful stats for tracking down slow pages and functions. You can get an even more interesting breakdown of this by then clicking on the &amp;quot;View Full Callgraph&amp;quot; link. This callgraph makes it easy to see where the slow parts of each particular run are and functions which individually may not take a long time to run but which are run thousands of times and thus resulting in a great deal of slowdown.&lt;br /&gt;
[[Image:profilingSettings.png|frame|center|Enabling profiling and setting it to run on all pages via a wildcard]]&lt;br /&gt;
[[Image:profilingRuns.png|frame|left|A profiling runs option can be seen after enabling profiling]]&lt;br /&gt;
&lt;br /&gt;
==Using Tideways/XHProf==&lt;br /&gt;
&lt;br /&gt;
MDL-39443 shows the kind of thing that can be done using XHProf.&lt;br /&gt;
&lt;br /&gt;
[http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html This blog post] talks about the process.&lt;br /&gt;
&lt;br /&gt;
Since Moodle 2.5.1 it&#039;s possible to export and import any profiling run. That enables some interesting uses like, comparisons along the time, between different systems and sharing or runs in other systems like the Tracker when optimization issues are being fixed.&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Setting_up_xhprof_on_Moodle&amp;diff=56352</id>
		<title>Setting up xhprof on Moodle</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Setting_up_xhprof_on_Moodle&amp;diff=56352"/>
		<updated>2019-09-02T15:33:20Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;The following instructions are for setting up tideways (the modern replacement for xhprof) for Moodle under a Ubuntu/Debian environment. The process should be similar for other linux enviroments, but will need some tweaking if you wish to do this under windows. Please update this document if you find any major problems.&lt;br /&gt;
&lt;br /&gt;
==Installing xhprof with Linux==&lt;br /&gt;
&lt;br /&gt;
=== Tideways ===&lt;br /&gt;
&lt;br /&gt;
Latest version:&lt;br /&gt;
&lt;br /&gt;
sudo apt-get install php-tideways&lt;br /&gt;
&lt;br /&gt;
Older version&lt;br /&gt;
&lt;br /&gt;
 sudo apt-get install tideways-php&lt;br /&gt;
&lt;br /&gt;
===Build manually===&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Add the following to the apache version of you php.ini file&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code bash&amp;gt;&lt;br /&gt;
phpenmod tideways&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Restart Apache&lt;br /&gt;
&amp;lt;code bash&amp;gt;&lt;br /&gt;
sudo service apache2 restart&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Create a file in your web root that makes a call to phpinfo(); and then view the result in your browser to make sure that tideways_xhprof is enabled in PHP. Checking the output of &#039;&#039;&#039;php -m&#039;&#039;&#039; would also work if you are sure that the command line version of PHP uses the same php.ini file as your web server.&lt;br /&gt;
&lt;br /&gt;
===Troubleshooting===&lt;br /&gt;
&lt;br /&gt;
==== Graph isn&#039;t generated ====&lt;br /&gt;
&lt;br /&gt;
If you see a &#039;&#039;&#039;failed to shell execute cmd=&amp;quot; dot -Tpng&#039;&#039;&#039; error when you follow the &#039;&#039;&#039;View Full Callgraph&#039;&#039;&#039; link you may need to install graphviz:&lt;br /&gt;
&lt;br /&gt;
 sudo apt-get install graphviz&lt;br /&gt;
&lt;br /&gt;
Into Windows environment this error can be caused by a path hardcoded into &amp;quot;\lib\xhprof\xhprof_lib\utils\callgraph_utils.php&amp;quot;, you must replace one parameter of the proc_open function which is a Linux path &amp;quot;/tmp&amp;quot; by a Windows one, like &amp;quot;c:/temp&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
==== Call to undefined function tideways_enable ====&lt;br /&gt;
&lt;br /&gt;
Verion 5 of tideways was renamed which broke things:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
Exception - Call to undefined function tideways_enable()&lt;br /&gt;
Debug info: &lt;br /&gt;
Error code: generalexceptionmessage&lt;br /&gt;
Stack trace:&lt;br /&gt;
line 168 of /lib/xhprof/xhprof_moodle.php: Error thrown&lt;br /&gt;
line 819 of /lib/setup.php: call to profiling_start()&lt;br /&gt;
line 53 of /config.php: call to require_once()&lt;br /&gt;
line 37 of /my/index.php: call to require_once()&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
One solution is to update everything to the latest, or you can force downgrade tideways to v4:&lt;br /&gt;
&lt;br /&gt;
 sudo apt install tideways-php=4.1.6&lt;br /&gt;
&lt;br /&gt;
See also for more details&lt;br /&gt;
&lt;br /&gt;
https://tideways.com/profiler/blog/tideways-no-5&lt;br /&gt;
&lt;br /&gt;
https://tracker.moodle.org/browse/MDL-62280&lt;br /&gt;
&lt;br /&gt;
==Installing xhprof with Windows==&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;This section needs to be updated for Tideways/PHP 7&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
You will need to download PHP extensions compiled for your version of PHP. [http://dev.freshsite.pl/php-extensions/xhprof.html Here is one source...]&lt;br /&gt;
&lt;br /&gt;
Extract the contained dll file to the ext directory of your server. With XAMPP this is in xampp\php\ext&lt;br /&gt;
&lt;br /&gt;
Add a line to your php.ini file that matches dll filename you are using. This goes in the Dynamic Extensions section.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code&amp;gt;&lt;br /&gt;
extension=xhprof_0.10.3_php54_vc9.dll&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Stop and restart Apache through your server control interface. If it complains, you probably don&#039;t have the correct extension for your version of PHP, or the extension entry in your php.ini file doesn&#039;t match the dll file.&lt;br /&gt;
&lt;br /&gt;
To test that the extension is installed, log in to Moodle as an administrator and navigate to Administration &amp;gt; Site administration &amp;gt; Server &amp;gt; PHP info. Search for information about the xhprof extension. It should be present and enabled.&lt;br /&gt;
&lt;br /&gt;
==Configuring Moodle to use xhprof==&lt;br /&gt;
&lt;br /&gt;
[[Image:profilingOption.png|thumb|left|The profiling option is displayed when the php xhprof extension is installed]]&lt;br /&gt;
[[Image:profilingOutput.png|thumb|right|Tabular profiling output produced by xhprof]]&lt;br /&gt;
[[Image:callgraph.png|thumb|right|An example call graph showing slow parts of the profiled run]]&lt;br /&gt;
Once the xhprof php extension is correctly installed you will find a new &amp;quot;Profiling&amp;quot; option available under Settings &amp;gt; Site administration &amp;gt; Development&lt;br /&gt;
&lt;br /&gt;
When you load the profiling settings page you are confronted with several options. In order to get xhprof up and running with minimal fuss you merely need to check the &amp;quot;Enable profiling&amp;quot; box and set a path that you wish to be profiled. You can simply set this to a wildcard using the asterisk symbol (&#039;&#039;&#039;*&#039;&#039;&#039;) while you are testing profiling. Afterwards you can come back and set this to a more restrictive setting once you know profiling is working. Note the paths need to be specified relative to your Moodle directory and not the web root.&lt;br /&gt;
&lt;br /&gt;
After you have enabled profiling you should load some pages within the &amp;quot;Profile these&amp;quot; filter that you set in the step above. Once you have done these go to Settings &amp;gt; Site administration &amp;gt; Development &amp;gt; Profiling runs and you should see a list of the pages you visited. Clicking on one of these and then clicking on the &amp;quot;View profiling details&amp;quot; will take you to a profiling table full of helpful stats for tracking down slow pages and functions. You can get an even more interesting breakdown of this by then clicking on the &amp;quot;View Full Callgraph&amp;quot; link. This callgraph makes it easy to see where the slow parts of each particular run are and functions which individually may not take a long time to run but which are run thousands of times and thus resulting in a great deal of slowdown.&lt;br /&gt;
[[Image:profilingSettings.png|frame|center|Enabling profiling and setting it to run on all pages via a wildcard]]&lt;br /&gt;
[[Image:profilingRuns.png|frame|left|A profiling runs option can be seen after enabling profiling]]&lt;br /&gt;
&lt;br /&gt;
==Using Tideways/XHProf==&lt;br /&gt;
&lt;br /&gt;
MDL-39443 shows the kind of thing that can be done using XHProf.&lt;br /&gt;
&lt;br /&gt;
[http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html This blog post] talks about the process.&lt;br /&gt;
&lt;br /&gt;
Since Moodle 2.5.1 it&#039;s possible to export and import any profiling run. That enables some interesting uses like, comparisons along the time, between different systems and sharing or runs in other systems like the Tracker when optimization issues are being fixed.&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Profiling_PHP&amp;diff=56351</id>
		<title>Profiling PHP</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Profiling_PHP&amp;diff=56351"/>
		<updated>2019-09-02T15:28:45Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;PHP has two types of profiler:&lt;br /&gt;
* XHProf is a standard designed for capturing profile traces on live servers. It was originally designed by engineers at Facebook and is suitable for production environments.&lt;br /&gt;
* [http://www.xdebug.org/docs/profiler XDebug] is well known. and understood, and its trace output is supported by tools like [http://kcachegrind.sourceforge.net/html/Home.html KCachegrind]. It is not recommended for production environments.&lt;br /&gt;
&lt;br /&gt;
==Tideways (replacement for XHProf)==&lt;br /&gt;
&lt;br /&gt;
[https://tideways.com/profiler/downloads Tideways] is a PHP7-compatible replacement for XHProf, and support for this is built into Moodle. ([https://tideways.io/ Tideways] is a large, paid-for service, which helps to identify a range of issues with production servers. Whilst the service itself is a paid-for service, the instrumentation tooling is both Open Source, and free.)&lt;br /&gt;
&lt;br /&gt;
There are two variants of the plugin. You will almost certainly want the tideways_xhprof plugin.&lt;br /&gt;
&lt;br /&gt;
* [https://tideways.com/profiler/downloads tideways] - the original tool, which includes both xhprof instrumentation, and support for the Tideways service. This version is compatible with:&lt;br /&gt;
** Moodle 3.0.6&lt;br /&gt;
** Moodle 3.1.2&lt;br /&gt;
** Moodle 3.2 onwards&lt;br /&gt;
* [https://github.com/tideways/php-xhprof-extension tideways_xhprof] - a rewritten implementation of the original which only includes the xhprof instrumentation. Compatible with:&lt;br /&gt;
** Moodle 3.1.12&lt;br /&gt;
** Moodle 3.2.9&lt;br /&gt;
** Moodle 3.3.6&lt;br /&gt;
** Moodle 3.4.3&lt;br /&gt;
** Moodle 3.5 onwards&lt;br /&gt;
&lt;br /&gt;
For installation details please see https://github.com/tideways/php-xhprof-extension&lt;br /&gt;
&lt;br /&gt;
See&lt;br /&gt;
* [[Setting up xhprof on Moodle]]&lt;br /&gt;
* http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html&lt;br /&gt;
* https://docs.google.com/presentation/d/1MV4R71UBgPgzM6I9h_yDnYcxIJlgCoLBUDtJJr-TzNI/present#slide=id.i0 presentation about using XHProf&lt;br /&gt;
&lt;br /&gt;
=== Export Xhprof data to plugins ===&lt;br /&gt;
&lt;br /&gt;
Starting at 3.6, Moodle allows for a plugin to handle the Xhprof data and not insert the traces into the database as implemented in (MDL-63031)[https://tracker.moodle.org/browse/MDL-63031]&lt;br /&gt;
&lt;br /&gt;
To disable Moodle from writing traces to the database, add: &amp;quot;$CFG-&amp;gt;disableprofilingtodatabase = False;&amp;quot; into config.php&lt;br /&gt;
&lt;br /&gt;
Plugins will need to provide a _store_profiling_data function to handle the data.&lt;br /&gt;
&lt;br /&gt;
==Xdebug==&lt;br /&gt;
&lt;br /&gt;
[http://xdebug.org/docs/profiler Xdebug] is a powerful PHP debugging tool. The first release of Xdebug was in 2002, since that it keeps growing and remains popular among PHP developers. Among its major features are stack and function tracing, code coverage analysis, remote debugging and scripts profiling. As the page topic suggests, we will focus on its profiling feature, which provides developer with detailed information about the script performance, helps identifying which parts of the code are slow. Collected information is being stored in cachegrind compatible file and can be analysed using one of external tools, such as [http://kcachegrind.sourceforge.net/html/Home.html KCachegrind], [http://sourceforge.net/projects/wincachegrind/ WinCacheGrind], [http://code.google.com/p/xdebugtoolkit/ xdebugtoolkit] or web-based analyser [https://github.com/jokkedk/webgrind#readme Webgrind]. Xdebug is simple to install and operate, it does not require code changes.&lt;br /&gt;
&lt;br /&gt;
===Installing Xdebug extension===&lt;br /&gt;
&lt;br /&gt;
The first step that has to be done is installing Xdebug extension. This procedure depends on the OS you are using, but general idea is to obtain Xdebug php extension and specify full path to it using &#039;&#039;zend_extension&#039;&#039; setting in &#039;&#039;php.inf&#039;&#039; file. Official [http://www.xdebug.org/docs/install Xdebug installation documentation] explains its installation on Windows, installing through PEAR/PECL and compiling from source.&lt;br /&gt;
Xdebug has been packaged for many Linux distributions, so it can be installed using corresponding package management tool. On Debian or Ubuntu, for example one would need to execute:&lt;br /&gt;
&lt;br /&gt;
 # apt-get install php5-xdebug&lt;br /&gt;
&lt;br /&gt;
This will put &#039;&#039;xdebug.so&#039;&#039; in default php modules directory and create &#039;&#039;/etc/php5/conf.d/xdebug.ini&#039;&#039; file with single line:&lt;br /&gt;
&lt;br /&gt;
 zend_extension=/usr/lib/php5/20090626/xdebug.so&lt;br /&gt;
&lt;br /&gt;
Note that this is equal to specifying the same line in &#039;&#039;php.inf&#039;&#039;, example above just reflects split php configuration.&lt;br /&gt;
&lt;br /&gt;
Once the Xdebug extension is installed and specified in php configuration, one may restart the webserver and information about Xdebug should appear in &#039;&#039;phpinfo()&#039;&#039; function output. If not, make sure that &#039;&#039;zend_extension&#039;&#039; line is not commented out, extension file exists in specified location and refer to webserver logs for more details.&lt;br /&gt;
&lt;br /&gt;
===Configuring Xdebug Profiler===&lt;br /&gt;
&lt;br /&gt;
When Xdebug extension is installed, it is time to configure profiling functionality. (If you are running apache2 as your web server and are using split configuration files such as the default apt-get install mentioned above, these settings should be added to &amp;quot;/etc/php5/apache2/conf.d/xdebug.ini&amp;quot;.)  There are number of parameters related to profiling, all of them start with &#039;&#039;xdebug.profiler_&#039;&#039; prefix. First of all, profiler should be enabled. There are two ways of doing it. One way is keeping it always enabled, so profiling information will be generated on every page request:&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_enable=1&lt;br /&gt;
&lt;br /&gt;
Another way is making Xdebug writing profiling information on demand by triggering it with GET/POST or COOKIE variable named &#039;&#039;XDEBUG_PROFILE&#039;&#039;:&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_enable_trigger = 1&lt;br /&gt;
&lt;br /&gt;
This option is preferable for several reasons: profiling data files are relatively large especially on complex scripts and you may run out of disk-space pretty quick, it allows generating profiling information only when you need it, thus it is easier to find the generated file in output directory, finally, on demand profiling can be done on production servers, though it is not recommended. If you have enabled &#039;&#039;xdebug.profiler_enable_trigger&#039;&#039; option, make sure that &#039;&#039;xdebug.profiler_enable&#039;&#039; is disabled, otherwise this will lead to dump file being generated on each request.&lt;br /&gt;
&lt;br /&gt;
Whatever method of profiling enabling you have chosen, profiling data files will be generated on each request (or request with a trigger parameter) in directory specified with &#039;&#039;xdebug.profiler_output_dir&#039;&#039; directive. By default is it set to &#039;&#039;/tmp&#039;&#039;, but you may change it to any more suitable location.&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_output_dir=/tmp&lt;br /&gt;
&lt;br /&gt;
Generated file will be named in accordance with &#039;&#039;xdebug.profiler_output_name&#039;&#039; setting. This setting can handle some specifiers and use them in the file name. Default name pattern is &#039;&#039;cachegrind.out.%p&#039;&#039;; in the actual file name %p will be replaced with process ID value. The fill list of specifier can be found [http://www.xdebug.org/docs/all_settings#trace_output_name here]. More intuitive naming is recommended, so that it is easier to find the file you have just generated in the bunch of others:&lt;br /&gt;
&lt;br /&gt;
 xdebug.profiler_output_name=cachegrind.out.%R.%t&lt;br /&gt;
&lt;br /&gt;
With this naming pattern, timestamp and script name will be reflected in the file name.&lt;br /&gt;
&lt;br /&gt;
When you are done with configuration, it is time to test it. First of all, the webserver has to be restarted, so that the new config will come into effect. Depending on your operating system and web server, you should be able to restart it with a command similar to:&lt;br /&gt;
&lt;br /&gt;
 sudo service apache2 restart&lt;br /&gt;
&lt;br /&gt;
(This should work for apache2 on several flavours of Linux.)&lt;br /&gt;
&lt;br /&gt;
===Profiling a page===&lt;br /&gt;
&lt;br /&gt;
Now assuming that Xdebug was configured to use a trigger for script profiling, open any php page on your server in your browser having added &#039;&#039;XDEBUG_PROFILE&#039;&#039; parameter to URL string:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;http://servername/moodle2/index.php?XDEBUG_PROFILE&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
or if it already has some parameters, just add our trigger to the URL end:&lt;br /&gt;
&lt;br /&gt;
 &amp;lt;nowiki&amp;gt;http://servername/moodle2/mod/forum/view.php?id=5&amp;amp;XDEBUG_PROFILE&amp;lt;/nowiki&amp;gt;&lt;br /&gt;
&lt;br /&gt;
As a result, the new file should be generated in directory you specified with &#039;&#039;xdebug.profiler_output_dir&#039;&#039; directive:&lt;br /&gt;
&lt;br /&gt;
 cachegrind.out._moodle2_mod_forum_view_php.1289838411&lt;br /&gt;
 cachegrind.out._moodle2_index_php.1289837892&lt;br /&gt;
&lt;br /&gt;
Triggering profiling with POST requests or AJAX queries is also possible without code changes. [https://addons.mozilla.org/en-US/firefox/addon/58688/ Easy Xdebug] plugin for FireFox has profiling toggle button that inserts XDEBUG_PROFILE variable into cookie data, thus making profiling enabled for as long as you wish for all requests. Similar plugins exist for [https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc Chrome] and [https://github.com/benmatselby/xdebug-toggler Safari] browsers.&lt;br /&gt;
&lt;br /&gt;
===Analyzing Xdebug profiling files===&lt;br /&gt;
&lt;br /&gt;
As it was pointed out earlier, profiling data is recoded in cachegrind format, so it can be analysed using one of external tools, such as [https://kcachegrind.github.io/html/Home.html KCachegrind], [http://sourceforge.net/projects/wincachegrind/ WinCacheGrind], [http://code.google.com/p/xdebugtoolkit/ xdebugtoolkit] or web-based analyser [https://github.com/jokkedk/webgrind#readme Webgrind]. Using these tools is pretty simple. I prefer KCachegrind which has a feature to show the matching code if web-server is run on the same box. Xdebug profiler documentation page has a [http://xdebug.org/docs/profiler#misc section] about KCachegrind that worth reading for everyone who starts using KCachegrind.&lt;br /&gt;
&lt;br /&gt;
===Quick summary===&lt;br /&gt;
&lt;br /&gt;
1. Install XDebug extension on your server.&lt;br /&gt;
&lt;br /&gt;
2. Add something like this to your php.ini file:&lt;br /&gt;
 zend_extension = /usr/lib/php5/20090626/xdebug.so&lt;br /&gt;
 xdebug.profiler_enable = 0&lt;br /&gt;
 xdebug.profiler_enable_trigger = 1&lt;br /&gt;
 xdebug.profiler_output_dir = /var/tmp&lt;br /&gt;
 xdebug.profiler_output_name = cachegrind.out.%R.%t&lt;br /&gt;
or add something like this to your .htaccess file&lt;br /&gt;
 php_flag xdebug.profiler_enable off&lt;br /&gt;
 php_flag xdebug.profiler_enable_trigger on&lt;br /&gt;
 php_value xdebug.profiler_output_dir /var/tmp&lt;br /&gt;
 php_value xdebug.profiler_output_name cachegrind.out.%R.%t&lt;br /&gt;
&lt;br /&gt;
3. When you want to profile a page, add &amp;lt;tt&amp;gt;&amp;amp;XDEBUG_PROFILE&amp;lt;/tt&amp;gt; to the end of the URL.&lt;br /&gt;
&lt;br /&gt;
4. Open the &amp;lt;tt&amp;gt;cachegrind.out....&amp;lt;/tt&amp;gt; file that is generated with one of the tools mentioned above.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==See also==&lt;br /&gt;
&lt;br /&gt;
* [http://moodle.org/mod/forum/discuss.php?d=162045 Forum thread about profiling Moodle 2.0]&lt;br /&gt;
XHProf articles:&lt;br /&gt;
* [https://docs.google.com/present/view?id=dcbkgbgf_45fbg3rnmk&amp;amp; Presentation about XHProf]&lt;br /&gt;
* [http://techportal.ibuildings.com/2009/12/01/profiling-with-xhprof/ Profiling with XHProf]&lt;br /&gt;
* [http://www.open.ac.uk/blogs/XHProf/?page_id=46 XHProf – Profiling and Reporting] from Moodle perspective written by [http://moodle.org/user/view.php?id=264538&amp;amp;course=5 James Brisland]&lt;br /&gt;
Xdebug articles:&lt;br /&gt;
* [http://devzone.zend.com/article/2803-Introducing-xdebug Introducing xdebug]&lt;br /&gt;
* [http://blog.teamlazerbeez.com/2010/05/04/xdebug-quickstart-profiling-in-php/ Xdebug Quickstart: Profiling in PHP]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Postgres_Tuning_For_Developers&amp;diff=56273</id>
		<title>Postgres Tuning For Developers</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Postgres_Tuning_For_Developers&amp;diff=56273"/>
		<updated>2019-07-11T18:49:59Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* Changes */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;These are instructions for tuning a default Postgres 9.1.7 install on Ubuntu (12.04) with 16GB of RAM.&lt;br /&gt;
&lt;br /&gt;
These instructions are intended for development machines only - not production environments. &lt;br /&gt;
&lt;br /&gt;
These are based on recommendations from here: http://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server&lt;br /&gt;
&lt;br /&gt;
First - results:&lt;br /&gt;
&lt;br /&gt;
Before changes - unit tests on master took ~ 09:00 &lt;br /&gt;
&lt;br /&gt;
After changes - unit tests on master took 05:48&lt;br /&gt;
&lt;br /&gt;
=Changes=&lt;br /&gt;
&lt;br /&gt;
Change Setting in postgresql.conf. (The path will depend on your system, e.g. Linux: /etc/postgresql/9.1/main/postgresql.conf Mac: /Library/PostgreSQL/9.3/data/postgresql.conf)&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
shared_buffers = 512MB # Recommended 1/4 of RAM - I&#039;m leaving this lower on a dev machine (still up from 24MB)&lt;br /&gt;
&lt;br /&gt;
effective_cache_size = 8GB # Recommended 1/2 of RAM&lt;br /&gt;
checkpoint_segments = 20 # Recommended minimum -- Don&#039;t do this in Postgres 11. This setting no longer exists.&lt;br /&gt;
checkpoint_completion_target = 0.9 # Up from 0.5&lt;br /&gt;
work_mem = 20MB # Used for in memory sorts&lt;br /&gt;
synchronous_commit = off # Fine only for dev machines&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Append File:&lt;br /&gt;
/etc/sysctl.conf&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
# Postgres tuning&lt;br /&gt;
kernel.shmmax=1073741824&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Reboot!&lt;br /&gt;
&lt;br /&gt;
=Don&#039;t bother with a RAM disk=&lt;br /&gt;
&lt;br /&gt;
* sam and Tim have tested using a RAM disk for phpunit runs on Windows and found no improvement once these settings are in place (even when main drive is an HD not an SSD).&lt;br /&gt;
* Eloy also did some testing without significant improvements.&lt;br /&gt;
* NOTE: This is not true of MySQL, where significant gains can be seen.&lt;br /&gt;
&lt;br /&gt;
[[Category:Developer tools]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Form_API&amp;diff=56217</id>
		<title>Form API</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Form_API&amp;diff=56217"/>
		<updated>2019-07-02T17:09:10Z</updated>

		<summary type="html">&lt;p&gt;Timhunt: /* disableif() */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;==Overview==&lt;br /&gt;
Web Forms in moodle are created using forms API. Form API supports all html elements (checkbox, radio, textbox etc), with improved accessibility and security.&lt;br /&gt;
==Highlights==&lt;br /&gt;
# Tested and optimised for use on major screen-readers Dragon and JAWS. &lt;br /&gt;
# Tableless layout.&lt;br /&gt;
# Process form data securely, with required_param, optional_param and session key.&lt;br /&gt;
# Supports client-side validation&lt;br /&gt;
# Facility to add Moodle help buttons to forms. &lt;br /&gt;
# Support for file repository using [[File_API]]&lt;br /&gt;
# Support for many custom moodle specific and non-specific form elements.&lt;br /&gt;
# Addition for repeated elements.&lt;br /&gt;
# Addition for form elements in advance group&lt;br /&gt;
&lt;br /&gt;
==Usage==&lt;br /&gt;
For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
//moodleform is defined in formslib.php&lt;br /&gt;
require_once(&amp;quot;$CFG-&amp;gt;libdir/formslib.php&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
class simplehtml_form extends moodleform {&lt;br /&gt;
    //Add elements to form&lt;br /&gt;
    public function definition() {&lt;br /&gt;
        global $CFG;&lt;br /&gt;
       &lt;br /&gt;
        $mform = $this-&amp;gt;_form; // Don&#039;t forget the underscore! &lt;br /&gt;
&lt;br /&gt;
        $mform-&amp;gt;addElement(&#039;text&#039;, &#039;email&#039;, get_string(&#039;email&#039;)); // Add elements to your form&lt;br /&gt;
        $mform-&amp;gt;setType(&#039;email&#039;, PARAM_NOTAGS);                   //Set type of element&lt;br /&gt;
        $mform-&amp;gt;setDefault(&#039;email&#039;, &#039;Please enter email&#039;);        //Default value&lt;br /&gt;
            ...&lt;br /&gt;
    }&lt;br /&gt;
    //Custom validation should be added here&lt;br /&gt;
    function validation($data, $files) {&lt;br /&gt;
        return array();&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Then instantiate form (in this case simplehtml_form) on your page.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
//include simplehtml_form.php&lt;br /&gt;
require_once(&#039;PATH_TO/simplehtml_form.php&#039;);&lt;br /&gt;
&lt;br /&gt;
//Instantiate simplehtml_form &lt;br /&gt;
$mform = new simplehtml_form();&lt;br /&gt;
&lt;br /&gt;
//Form processing and displaying is done here&lt;br /&gt;
if ($mform-&amp;gt;is_cancelled()) {&lt;br /&gt;
    //Handle form cancel operation, if cancel button is present on form&lt;br /&gt;
} else if ($fromform = $mform-&amp;gt;get_data()) {&lt;br /&gt;
  //In this case you process validated data. $mform-&amp;gt;get_data() returns data posted in form.&lt;br /&gt;
} else {&lt;br /&gt;
  // this branch is executed if the form is submitted but the data doesn&#039;t validate and the form should be redisplayed&lt;br /&gt;
  // or on the first display of the form.&lt;br /&gt;
&lt;br /&gt;
  //Set default data (if any)&lt;br /&gt;
  $mform-&amp;gt;set_data($toform);&lt;br /&gt;
  //displays the form&lt;br /&gt;
  $mform-&amp;gt;display();&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you wish to use the form within a block then you should consider using the render method, as demonstrated below:&lt;br /&gt;
&lt;br /&gt;
Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you&#039;ve included the file which contains the class for your Moodle form.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
class block_yourblock extends block_base{&lt;br /&gt;
	public function init(){&lt;br /&gt;
		$this-&amp;gt;title = &#039;Your Block&#039;;&lt;br /&gt;
	}&lt;br /&gt;
	public function get_content(){&lt;br /&gt;
&lt;br /&gt;
		$this-&amp;gt;content = new stdClass();&lt;br /&gt;
		$this-&amp;gt;content-&amp;gt;text = &#039;&#039;;&lt;br /&gt;
&lt;br /&gt;
		$mform = new simplehtml_form();&lt;br /&gt;
&lt;br /&gt;
		//Form processing and displaying is done here&lt;br /&gt;
		if ($mform-&amp;gt;is_cancelled()) {&lt;br /&gt;
			//Handle form cancel operation, if cancel button is present on form&lt;br /&gt;
		} else if ($fromform = $mform-&amp;gt;get_data()) {&lt;br /&gt;
			//In this case you process validated data. $mform-&amp;gt;get_data() returns data posted in form.&lt;br /&gt;
		} else {&lt;br /&gt;
			// this branch is executed if the form is submitted but the data doesn&#039;t validate and the form should be redisplayed&lt;br /&gt;
			// or on the first display of the form.&lt;br /&gt;
&lt;br /&gt;
			//Set default data (if any)&lt;br /&gt;
			$mform-&amp;gt;set_data($toform);&lt;br /&gt;
&lt;br /&gt;
			//displays the form&lt;br /&gt;
			$this-&amp;gt;content-&amp;gt;text = $mform-&amp;gt;render();&lt;br /&gt;
		}&lt;br /&gt;
&lt;br /&gt;
		return $this-&amp;gt;content;&lt;br /&gt;
&lt;br /&gt;
	}&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Form elements==&lt;br /&gt;
===Basic form elements===&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button button]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox checkbox]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio radio]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select select]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select multi-select]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password password]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden hidden]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html html] - div element&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static static] - Display a static text.&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text text]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]&lt;br /&gt;
&lt;br /&gt;
===Custom form elements===&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask passwordunmask] - A password element with option to show the password in plaintext.&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha recaptcha]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno selectyesno]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink selectwithlink]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector date_selector]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector date_time_selector]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration duration]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor editor]&lt;br /&gt;
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filepicker filepicker] - upload single file&lt;br /&gt;
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filemanager filemanager] - upload multiple files&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags tags]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup addGroup]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade modgrade]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible modvisible]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile choosecoursefile]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]&lt;br /&gt;
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]&lt;br /&gt;
&lt;br /&gt;
==Commonly used functions==&lt;br /&gt;
&lt;br /&gt;
====add_action_buttons($cancel = true, $submitlabel=null);====&lt;br /&gt;
&lt;br /&gt;
You will normally use this helper function which is a method of moodleform to add all the &#039;action&#039; buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string(&#039;savechanges&#039;). Note the &#039;&#039;&#039;$this&#039;&#039;&#039; not &#039;&#039;&#039;$mform&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
   $this-&amp;gt;add_action_buttons();&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#setDefault_2|setDefault()]]====&lt;br /&gt;
To set the default value for an element.&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#disabledIf|disabledIf()]]====&lt;br /&gt;
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#hideIf|hideif()]]====&lt;br /&gt;
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.&lt;br /&gt;
Same syntax as disabledIf. Can do a simple search and replace on disabledIf.  Added in Moodle 3.4.&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#addRule|addRule()]]====&lt;br /&gt;
Add rule for server/client side validation. Like text field is required element and is of type email.&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#setHelpButton|setHelpButton()]]====&lt;br /&gt;
Sets pop-up help button to a form element.&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====&lt;br /&gt;
Adds pop-up help button to a form element&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#setType|setType()]]====&lt;br /&gt;
PARAM_* types are used to specify how a submitted variable should be cleaned.&lt;br /&gt;
&lt;br /&gt;
====[[lib/formslib.php_Form_Definition#disable_form_change_checker|disable_form_change_checker()]]====&lt;br /&gt;
By default, any Moodle form will pop-up an &amp;quot;Are you sure?&amp;quot; alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call &amp;lt;tt&amp;gt;$mform-&amp;gt;disable_form_change_checker()&amp;lt;/tt&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
==FAQ==&lt;br /&gt;
[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]&lt;br /&gt;
==See also==&lt;br /&gt;
&lt;br /&gt;
* [[Core_APIs]]&lt;br /&gt;
* [[lib/formslib.php_Usage]] &lt;br /&gt;
* [[lib/formslib.php_Form_Definition]]&lt;br /&gt;
* [[Designing usable forms]]&lt;br /&gt;
* [[Fragment]]&lt;br /&gt;
* [[MForm_Modal]]&lt;br /&gt;
&lt;br /&gt;
[[Category:API]]&lt;/div&gt;</summary>
		<author><name>Timhunt</name></author>
	</entry>
</feed>