MoodleDocs - User contributions [en]

Acceptance testing/Compatibility changes

2021-09-19T08:38:26Z

Scaroodle: "Edit settings" is now "Settings". Refs: MDL-72093

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.
= Compatibility changes =
== Moodle 3.3 ==
=== And I follow "Course 1" ===
<b>Summary</b>
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage<br>And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}
{| class="wikitable"
|-
|+Examples
|-
|Before
|<syntaxhighlight lang="php">
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</syntaxhighlight>
|-
|After
|<syntaxhighlight lang="php">
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</syntaxhighlight>
|}
<b>Why did this change?</b>

UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.
== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===
<b>Summary</b>
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}
{| class="wikitable"
|-
|+Examples
|-
|Before
|<syntaxhighlight lang="php">
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</syntaxhighlight>
|-
|After
|<syntaxhighlight lang="php">
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</syntaxhighlight>
|}
<b>Why did this change?</b>

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

Note: since 4.0 ''Edit Settings'' has been changed into ''Settings''. Refs: MDL-72093.
=== And I navigate to "Participants" node in "My courses > C1" ===
<b> Summary </b>
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1"<br>And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}
{| class="wikitable"
|-
|+Examples
|-
|Before
|<syntaxhighlight lang="php">
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</syntaxhighlight>
|-
|After
|<syntaxhighlight lang="php">
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants
</syntaxhighlight>
|}
<b> Why did this change? </b>

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.
== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.
= See also =
* [[Running_acceptance_test]]
[[Category:Quality Assurance]]
[[Category:Behat]]

Moodle 3.9.10 release notes

2021-09-13T06:23:21Z

Scaroodle: Add MDL-72494, being critical for the recent regression in M93 (Fixed in M94)

<p class="note">'''This version of Moodle is no longer supported for general bug fixes.''' You are encouraged to [[:en:Upgrading|upgrade]] to a supported version of Moodle.</p>
[[Releases]] > {{FULLPAGENAME}}

Release date: 13 September 2021

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.9.10%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.9.10].
==Backported bug fixes==
* MDL-72494 - Cannot change course format with Chrome 93.0
* MDL-72312 - PHP 7.2 tests failing in 3.10 & 3.9, caused by buggy php-igbinary extension
* MDL-72265 - Backup code added in MDL-56310 incorrectly checks moodle/role:safeoverride for users who already have moodle/role:override
==Backported security improvements==
* MDL-72014 - Update grunt and some components to avoid some security reports
* MDL-72187 - Log visibility change of log stores
==See also==
*[[Moodle 3.9.9 release notes]]
[[Category:Release notes]]
[[Category:Moodle 3.9]]
[[fr:Notes de mise à jour de Moodle 3.9.10]]
[[es:Notas de Moodle 3.9.10]]

Travis integration

2021-02-19T21:05:56Z

Scaroodle: Fix typo

Given the two notes below, you probably don't want to read this page. [[Github actions integration]] is much more likely to be what you want.

<div class="note">Travis [https://mailchi.mp/3d439eeb1098/travis-ciorg-is-moving-to-travis-cicom has announced] that '''travis-ci.org will be closed down completely on December 31st 2020''', with travis-ci.com becoming the unified place for all projects. More information can be found at:
* [https://docs.travis-ci.com/user/migrate/open-source-repository-migration Migrating repositories to travis-ci.com]
* Moodle Tracker: MDLSITE-6246</div>
<div class="note">Travis [https://blog.travis-ci.com/2020-11-02-travis-ci-new-billing has announced], November 2, 2020, that '''travis-ci.com won't be (unlimitedly) free anymore''', with everybody getting some credits (processing time) once and, after using them, you must change to some of their (paid) plans. Few weeks later, November 24, 2020, [https://blog.travis-ci.com/oss-announcement they have published an update] specifically for Open Source. There, they recommend to contact them ''"for anything relating with your open source account"''. Up to you!
More information can be found at:
* Moodle Tracker: MDL-70265</div>

== Moodle core ==

=== Background ===

Moodle is regularly tested against a matrix of Databases, PHP Versions, and operating systems, however many developers do not have the resources available to run on many of these combinations before pushing an issue for integration as they are time-consuming to both set up and to run.

There are many Continuous Integration tools available to developers, and Travis-CI is just one of those available to the Open Source community.

Since version 3.0, Moodle includes a Travis configuration file in its repository. This configuration file configures and controls a Travis build across a matrix of testing environments. This allows developers pushing patches to Moodle to have their code unit tested before it reaches integration. The hope is that the availability of this integration should reduce the number of unit test failures seen during Integration.

Note: Moodle HQ uses the Jenkins CI platform and this should be seen as the [https://ci.moodle.org/ canonical CI server for Moodle]. The Travis integration aims is to provide early warning to developers of any issues with their code.

=== Usage ===

Travis-CI is available and is usually configured to run automatically when pushing code, but it must be configured before first use.

For the purpose of this documentation, it is assumed that you are pushing to a public Moodle repository on GitHub. Other integrations are supported, but the service available from Travis is only available to public repositories.

=== Setup ===

# [https://travis-ci.com/auth Sign in to Travis CI] using your GitHub account
# Once you’re signed in, and the initial synchronisation of your GitHub repositories has completed, go to your [https://travis-ci.com/profile profile page]
# Enable Travis CI for your clone of the Moodle repository [[File:moodle-travis-enable.png]]
# Click on the cog icon to configure the Integration
# Ensure that "Build pushed branches" is enabled [[File:moodle-travis-settings-2020.png]]
# Email notifications will be sent by default to the committer and the commit author. If you want to turn off email notifications for this repository, you can define an environment variable with name MOODLE_EMAIL and "no" as value.
# By default, the following jobs will be executed for each branch sent to github:
## GRUNT: 1 job that will check that all your javascript and scss has been properly built (see [[Grunt]]) and is part of the patch.
## CITESTS: 1 job that will perform a lightweight linting of your branch.
## PHPUNIT: 1 job that will run all the unit tests on your branch (using the lowest PHP version supported by the branch and PostgreSQL as database).
# If you want to change those defaults, you can use the following environment variables:
## MOODLE_DATABASE: With value "mysqli" to switch your runs to that database. With value "all" to run both PostgreSQL and MySQL unit tests.
## MOODLE_PHP: With value "all", to run the unit tests both with the lowest and the highest PHP versions supported by the branch.
Note that adding more jobs will increase the time needed (and the credits consumed) for processing each branch, so be careful picking your fav configuration.
[[File:environment_variables.png|Define an environment variable]]

=== How do I start a build? ===

It won't build immediately after setup. Builds start automatically when you push a change.

== Moodle plugins ==

See [https://moodlehq.github.io/moodle-plugin-ci/ Moodle Plugin CI repository] for setup instructions.

Related discussions:
* [https://moodle.org/mod/forum/discuss.php?d=323384 Adding Travis CI support into your plugin]
* [https://moodle.org/mod/forum/discuss.php?d=389744 Recent Travis-CI issues with plugins]

=== Ignoring files and folders ===

For some of the code analysis tools, it is important to ignore some files within the plugin because they might not be fixable, like a third party library. The all code analysis commands in this project ignore files and directories listed in the thirdpartylibs.xml plugin file. See https://docs.moodle.org/dev/Plugin_files#thirdpartylibs.xml for more info.

==== Ignoring files ====

Specifically for the codechecker command, you can ignore a single line, a section of a file or the whole file by using specific PHP comments. For details see this [[CodeSniffer]] wiki page.
In addition, you can ignore additional files by defining IGNORE_PATHS and/or IGNORE_NAMES environment variables in your .travis.yml file. These environment variables wont work for Grunt tasks, but will for everything else. Example:
<code php>
env:
global:
- MOODLE_BRANCH=MOODLE_35_STABLE
- IGNORE_PATHS=vendor/widget,javascript/min-lib.js
- IGNORE_NAMES=*-m.js,bad_lib.php
matrix:
- DB=pgsql
- DB=mysqli
</code>
Both environment variables take a CSV value. For IGNORE_PATHS, it takes relative file paths to ignore. File paths can be a simple string like foo/bar or a regular expression like /^foo\/bar/. For IGNORE_NAMES, it takes file names to ignore. File names can be a simple string like foo.php, a glob like *.php or a regular expression like /\.php$/.

If you need to specify ignore paths for a specific command, then you can define additional environment variables. The variable names are the same as above, but prefixed with COMMANDNAME_. Example:

<code php>
env:
global:
- MOODLE_BRANCH=MOODLE_35_STABLE
- IGNORE_PATHS=vendor/widget,javascript/min-lib.js
- IGNORE_NAMES=*-m.js,bad_lib.php
- PHPUNIT_IGNORE_PATHS=$IGNORE_PATHS,cli
matrix:
- DB=pgsql
- DB=mysqli
</code>
In the above example, we are adding the cli path to our ignore paths for the PHPUnit command (this is also how you can ignore files for code coverage). Please note that this is a complete override and there is no merging with IGNORE_PATHS and IGNORE_NAMES. So, in the above, the PHPUnit command would not ignore the file names defined in IGNORE_NAMES.

== See also ==

* [[Github actions integration]]: For information about the, also supported, integration with GitHub Actions.

[[Category:Developer tools]]

Git for developers

2021-01-26T20:22:40Z

Scaroodle: Add GH Actions too - Available soon even for Plugins

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

4. If you want, you can set up [[Travis integration]] with your GitHub repository so that when you push your code, Travis will automatically run a suite of tests for you against your changes. This way you can quickly catch issues without having to set up a testing environment locally (and before you share your code with other Moodle developers!). Another option to automate the execution of the Moodle test suite is to setup [[Github actions integration]].

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/bash
git fetch upstream
for BRANCH in MOODLE_{19..39}_STABLE MOODLE_{310..311}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:refs/heads/$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-master_brief_name origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

For the commit message, please do respect the guidelines given on in the article [[Coding style#Git_commits|Coding_style]].

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push origin MDL-xxxxx-master_brief_name

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase --interactive''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it, for example: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-master_brief_name" you will get an error message suggesting you to force push.
To force push the changed commits use:

git push -f origin MDL-xxxxx-master_brief_name

If an error occurs because you are still using the git protocol (read only), use this command :

git remote set-url origin https://github.com/<user.name>/moodle.git

A prompt will ask for your credentials, if you previously setup your SSH public key you can also use this one :

git remote set-url origin git@github.com:<user.name>/moodle.git

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-master_accepted_branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxxx-master_branch_to_delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-master_topic_branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxxx-20_brief_name), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxxx-21_topic that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxxx-master_topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxxx-master_topic origin/master (1)
git fetch ../moodle21 MDL-xxxxx-21_topic (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the master. The command (2) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (3) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxxx-21_topic from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxxx-21_topic (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxxx-master_topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

* [[Git tips]]

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [https://mirrors.edge.kernel.org/pub/software/scm/git/docs/giteveryday.html Everyday GIT With 20 Commands Or So]
* [https://git-scm.com/book/en/v2 'Pro Git' complete book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]
* [https://github.com/k88hudson/git-flight-rules/blob/master/README.md#flight-rules-for-git Flight rules for Git]

[[Category:Git]]

[[ja:開発者用Git]]

Moodle 3.11 release notes

2021-01-25T14:44:09Z

Scaroodle: Fixed what "other" PHP versions are (is) supported

[[Releases]] > {{FULLPAGENAME}}

Release date: Not yet released - scheduled for 10 May 2021

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

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

==Server requirements==

''Note: Requirements still to be reviewed and updated as necessary!''

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

* Moodle upgrade: Moodle 3.6 or later
* PHP version: minimum PHP 7.3.0 ''Note: minimum PHP version has increased since Moodle 3.10''. PHP 7.4.x is supported too. See [[Moodle and PHP]] for details.
* PHP extension '''sodium''' is required (it was previously only recommended)

=== Database requirements ===

''Note: Requirements still to be reviewed and updated as necessary!''

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

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

==Client requirements==

=== Browser support ===

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

Desktop:
* Chrome
* Firefox
* Safari
* Edge

''Note: Moodle 3.10 does NOT support Internet Explorer 11.''

Safari 7 and below has known compatibility issues with Moodle 3.10.

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date. https://www.whatsmybrowser.org/

==Major features==

==Other highlights==

==Security issues==

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

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

[[Category:Release notes]]
[[Category:Moodle 3.11]]

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

Travis integration

2020-11-26T22:03:31Z

Scaroodle: Typo

<div class="note">Travis [https://mailchi.mp/3d439eeb1098/travis-ciorg-is-moving-to-travis-cicom has announced] that '''travis-ci.org will be closed down completely on December 31st 2020''', with travis-ci.com becoming the unified place for all projects. More information can be found at:
* [https://docs.travis-ci.com/user/migrate/open-source-repository-migration Migrating repositories to travis-ci.com]
* Moodle Tracker: MDLSITE-6246</div>
<div class="note">Travis [https://blog.travis-ci.com/2020-11-02-travis-ci-new-billing has announced], November 2, 2020, that '''travis-ci.com won't be (unlimitedly) free anymore''', with everybody getting some credits (processing time) once and, after using them, you must change to some of their (paid) plans. Few weeks later, November 24, 2020, [https://blog.travis-ci.com/oss-announcement they have published an update] specifically for Open Source. There, they recommend to contact them ''"for anything relating with your open source account"''. Up to you!
More information can be found at:
* Moodle Tracker: MDL-70265</div>

== Moodle core ==

=== Background ===

Moodle is regularly tested against a matrix of Databases, PHP Versions, and operating systems, however many developers do not have the resources available to run on many of these combinations before pushing an issue for integration as they are time-consuming to both set up and to run.

There are many Continuous Integration tools available to developers, and Travis-CI is just one of those available to the Open Source community.

Since version 3.0, Moodle includes a Travis configuration file in its repository. This configuration file configures and controls a Travis build across a matrix of testing environments. This allows developers pushing patches to Moodle to have their code unit tested before it reaches integration. The hope is that the availability of this integration should reduce the number of unit test failures seen during Integration.

Note: Moodle HQ uses the Jenkins CI platform internally and this should be seen as the canonical CI server for Moodle. The Travis integration provided is to provide early warning to developers of any issues with their code.

=== Usage ===

Travis-CI is available and is usually configured to run automatically when pushing code, but it must be configured before first use.

For the purpose of this documentation, it is assumed that you are pushing to a public Moodle repository on GitHub. Other integrations are supported, but the service available from Travis is only available to public repositories.

=== Setup ===

# [https://travis-ci.com/auth Sign in to Travis CI] using your GitHub account
# Once you’re signed in, and the initial synchronisation of your GitHub repositories has completed, go to your [https://travis-ci.com/profile profile page]
# Enable Travis CI for your clone of the Moodle repository [[File:moodle-travis-enable.png]]
# Click on the cog icon to configure the Integration
# Ensure that "Build pushed branches" is enabled [[File:moodle-travis-settings-2020.png]]
# Email notifications will be sent by default to the committer and the commit author. If you want to turn off email notifications for this repository, you can define an environment variable with name MOODLE_EMAIL and "no" as value.
# By default, the following jobs will be executed for each branch sent to github:
## GRUNT: 1 job that will check that all your javascript and scss has been properly built (see [[Grunt]]) and is part of the patch.
## CITESTS: 1 job that will perform a lightweight linting of your branch.
## PHPUNIT: 1 job that will run all the unit tests on your branch (using the lowest PHP version supported by the branch and PostgreSQL as database).
# If you want to change those defaults, you can use the following environment variables:
## MOODLE_DATABASE: With value "mysqli" to switch your runs to that database. With value "all" to run both PostgreSQL and MySQL unit tests.
## MOODLE_PHP: With value "all", to run the unit tests both with the lowest and the highest PHP versions supported by the branch.
Note that adding more jobs will increase the time needed (and the credits consumed) for processing each branch, so be careful picking your fav configuration.
[[File:environment_variables.png|Define an environment variable]]

=== How do I start a build? ===

It won't build immediately after setup. Builds start automatically when you push a change.

== Moodle plugins ==

See [https://moodlehq.github.io/moodle-plugin-ci/ Moodle Plugin CI repository] for setup instructions.

Related discussions:
* [https://moodle.org/mod/forum/discuss.php?d=323384 Adding Travis CI support into your plugin]
* [https://moodle.org/mod/forum/discuss.php?d=389744 Recent Travis-CI issues with plugins]

=== Ignoring files and folders ===

For some of the code analysis tools, it is important to ignore some files within the plugin because they might not be fixable, like a third party library. The all code analysis commands in this project ignore files and directories listed in the thirdpartylibs.xml plugin file. See https://docs.moodle.org/dev/Plugin_files#thirdpartylibs.xml for more info.

==== Ignoring files ====

Specifically for the codechecker command, you can ignore a single line, a section of a file or the whole file by using specific PHP comments. For details see this [[CodeSniffer]] wiki page.
In addition, you can ignore additional files by defining IGNORE_PATHS and/or IGNORE_NAMES environment variables in your .travis.yml file. These environment variables wont work for Grunt tasks, but will for everything else. Example:
<code php>
env:
global:
- MOODLE_BRANCH=MOODLE_35_STABLE
- IGNORE_PATHS=vendor/widget,javascript/min-lib.js
- IGNORE_NAMES=*-m.js,bad_lib.php
matrix:
- DB=pgsql
- DB=mysqli
</code>
Both environment variables take a CSV value. For IGNORE_PATHS, it takes relative file paths to ignore. File paths can be a simple string like foo/bar or a regular expression like /^foo\/bar/. For IGNORE_NAMES, it takes file names to ignore. File names can be a simple string like foo.php, a glob like *.php or a regular expression like /\.php$/.

If you need to specify ignore paths for a specific command, then you can define additional environment variables. The variable names are the same as above, but prefixed with COMMANDNAME_. Example:

<code php>
env:
global:
- MOODLE_BRANCH=MOODLE_35_STABLE
- IGNORE_PATHS=vendor/widget,javascript/min-lib.js
- IGNORE_NAMES=*-m.js,bad_lib.php
- PHPUNIT_IGNORE_PATHS=$IGNORE_PATHS,cli
matrix:
- DB=pgsql
- DB=mysqli
</code>
In the above example, we are adding the cli path to our ignore paths for the PHPUnit command (this is also how you can ignore files for code coverage). Please note that this is a complete override and there is no merging with IGNORE_PATHS and IGNORE_NAMES. So, in the above, the PHPUnit command would not ignore the file names defined in IGNORE_NAMES.

== See also ==

* [[Talk:Travis Integration]] for previous Travis dev docs

[[Category:Developer tools]]

Javascript Modules

2019-12-12T08:24:10Z

Scaroodle: Adding a reference to examples of JS issues starting from 3.8

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://github.com/lukehoban/es6features#readme ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running Grunt, even with the cachejs config setting set to false (i.e. "Development mode").

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

This means you first have to '''install nodejs''' - and its package manager [https://www.npmjs.com/ npm]. The details of how to install those packages will vary by operating system, but on Linux it's probably similar to "sudo apt-get install nodejs npm". There are downloadable packages for other operating systems here: http://nodejs.org/download/. Moodle currently requires node {{NodeJSVersion}}.

Once this is done, you can '''run the command''':

npm install
npm install -g grunt-cli

from the top of the Moodle directory to install all of the required tools. (You may need extra permissions to use the -g option.)

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run Grunt in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== ES6 Modules (Moodle v3.8 and above) ==

In addition to AMD module syntax Moodle now supports the [https://github.com/lukehoban/es6features#modules ES6 syntax] for writing Javascript modules. All modules (defined using either syntax) are compatible with one another. Behind the scenes the ES6 module syntax is converted into an AMD syntax as part of the Babel compiling process.

=== Export default ===
There is one slight difference between the ES6 definition for exporting modules and the RequireJS (AMD) definition.

ES6 allows you to export a “default” value which is actually no different to exporting a named value where the name is “default”. Unfortunately, RequireJS allows for unnamed default exports (e.g. you can do "return SomeClass;") which can be imported by just requiring them in other AMD modules.

That’s a bit confusing, get to the point! Well, it basically means that in Moodle you won’t be able to write an ES6 module that exports both a default and named exports, e.g. "export default function() {...}" and "export const FOO = 'bar'" in the same module. The export default will simply override all other exports in that module.

=== Inline Javascript ===
Another important note is that ES6 support is only for stand alone Javascript files because it relies on the compilation from Babel and Grunt. That means any inline Javascript (either in PHP or in Mustache templates) won't support the ES6 features. Instead it would be best to keep the inline Javascript as minimal as possible and only use it to load a stand alone Javascript module.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
define(['jquery', 'core/str', 'core/ajax'], function($, str, ajax) {
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>
<br>
Note: It could be useful when you wish to pass a big chunk of data from php directly into a JS variable, to workaround MDL-62468 .<br>
Example: https://github.com/moodle/moodle/blob/master/media/player/videojs/classes/plugin.php#L386

===More examples of including 3rd-party JS modules===
* [https://moodle.org/mod/forum/discuss.php?d=327579#p1317252 Adding custom js via AMD (highcharts) to essential theme]

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.
*MDL-67327 JavaScript issues when not following the official documentation, since Moodle 3.8

[[Category:AJAX]]
[[Category:Javascript]]

Moodle 3.7 release notes

2019-05-02T13:06:06Z

Scaroodle: Added more changes from https://tracker.moodle.org/browse/MDL-63276 and https://tracker.moodle.org/browse/MDL-63420

[[Releases]] > {{FULLPAGENAME}}

Release date: Not yet released - scheduled for 13 May 2019

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

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

==Server requirements==

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

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

=== Database requirements ===

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

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

==Client requirements==

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

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

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date. https://whatbrowser.org

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

==Major features==

==Other Highlights==

===Security issues===

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

===For developers===

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

[[Category:Release notes]]
[[Category:Moodle 3.7]]

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

AJAX

2019-01-02T16:41:10Z

Scaroodle: Fixed a typo (to => two)

'''AJAX (Asynchronous Javascript and XML)''' is a modern web design technique that allows for more interactivity by making webpages that fetch data in the background and alter themselves without reloading the entire page. This helps to make a page feel much more like an application than a web page. AJAX is a new way of working with existing technologies (including HTML, [[Javascript]], [[CSS]] and the ''XMLHttpRequest object'' amongst others) rather than a new piece of technology in itself.

Although AJAX indicates that XML is used, the term really relates to the group of technologies and in Moodle we tend to favour use of JSON rather than XML as the syntax is lighter and leads to a smaller output. It is also easier to construct from php data structures.

== Ajax in Moodle ==
{{ Moodle 2.9 }}

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions.

Some benefits of this system are:
# No new ajax scripts need auditing for security vulnerabilities
# Multiple requests can be chained in a single http request
# Strict type checking for all parameters and return types
# New webservice functions benefit Ajax interfaces and web service clients

So the steps required to create an ajax interaction are:

# Write or find an existing web service function to handle the ajax interaction: See [[ Web_services ]]
# White list the web service for ajax. To do this, you can define 'ajax' => true in your function's definition, in db/services.php. Only functions that are whitelisted using this mechanism will be available to the ajax script.
# Call the web service from javascript in response to a user action:

Example calling core_get_string:
<code javascript>
require(['core/ajax'], function(ajax) {
var promises = ajax.call([
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'pluginname' } },
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'changerate' } }
]);

promises[0].done(function(response) {
console.log('mod_wiki/pluginname is' + response);
}).fail(function(ex) {
// do something with the exception
});

promises[1].done(function(response) {
console.log('mod_wiki/changerate is' + response);
}).fail(function(ex) {
// do something with the exception
});
});
</code>

Note: This example chains two separate calls to the 'core_get_string' webservice in one http request

Note: Don't actually fetch strings like this, it is just an example, use the 'core/str' module instead.

If there is only a single action, a simpler form is possible (example from Assignment):

<code>
ajax.call([{
methodname: 'mod_assign_submit_grading_form',
args: {assignmentid: assignmentid, userid: this._lastUserId, jsonformdata: JSON.stringify(data)},
done: this._handleFormSubmissionResponse.bind(this, data, nextUserId),
fail: notification.exception
}]);
</code>

('notifcation' comes from the 'core/notification' javascript module and provides a useful popup error message if the call fails)

To update parts of the UI in response to Ajax changes, consider using [[ Templates ]]

For information on writing AJAX scripts for Moodle before Moodle 2.9 see: [[ AJAX pre 2.9 ]]

Watch a video about using templates with webservices and AJAX in Moodle: https://www.youtube.com/watch?v=UTePjRZqAg8

Tricky things to know about using webservices with ajax calls:
# Any call to $PAGE->get_renderer() requires the correct theme be set. If this is done in a webservice - it is likely that the theme needs to be a parameter to the webservice.
# Text returned from a webservice must be properly filtered. This means it must go through external_format_text or external_format_string (since 3.0 - see MDL-51213) with the correct context.
# The correct context for 2 is the most specific context relating to the thing being output e.g. for a user's profile desciption the context is the user context.
# After adding any dynamic content to a page, Moodle's filters need to be notified via M.core.event.FILTER_CONTENT_UPDATED (MDL-51222 makes this easier)
# After adding or changing any webservice definition in db/services.php - you must bump the version number for either the plugin or Moodle and run the upgrade. This will install the webservice in the DB tables so it can be found by ajax.

In some very rare cases - you can mark webservices as safe to call without a session. These should only be used for webservices that return 100% public information and do not consume many resources. A current example is core_get_string. To mark a webservice as safe to call without a session you need to do 2 things.
# Add 'loginrequired' => false to the service definition in db/services.php
# Pass "false" as the 3rd argument to the ajax "call" method when calling the webservice.
The benefit to marking these safe webservice is that (a) they can be called from the login page before we have a session and (b) they will perform faster because they will bypass moodles session code when responding to the webservice call.

== See also ==

* [[ AJAX pre 2.9 ]]
* [[Templates]]
* [[Javascript Modules]]
* [[Javascript FAQ]]
* [[Javascript]]
* [[Firebug#Debugging_AJAX_with_Firebug|Debugging AJAX with Firebug]]

* [http://www.adaptivepath.com/publications/essays/archives/000385.php ''Ajax: A New Approach to Web Applications'', the original Ajax article by Adaptive Path] (This link is now dead, but the article is preserved on the [https://web.archive.org/web/20070225140912/http://www.adaptivepath.com/publications/essays/archives/000385.php Internet Archive])
* [http://developer.mozilla.org/en/docs/AJAX:Getting_Started ''AJAX: Getting Started'' article on developer.mozilla.org]
* [http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html ''10 places you must use AJAX'' by Adam Bosworth] (Also a dead link... [https://web.archive.org/web/20060127015713/http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html Internet Archive copy])
* [http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype ''Considering Ajax, Part 1: Cut through the hype'' from IBM developerworks] (Also a dead link... [https://web.archive.org/web/20080602101238/http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype Internet Archive copy])
* [http://en.wikipedia.org/wiki/Ajax_%28programming%29 Wikipedia article on ''AJAX'']
* [http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ How to Make Your AJAX Applications Accessible: 40 Tutorials and Articles] (Also a dead link... [https://web.archive.org/web/20090225094656/http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ Internet Archive copy])
*[http://www.ajaxload.info/ AJAX loading icon generator]

[[Category:Javascript]]
[[Category:AJAX]]

Deprecation

2018-06-08T08:34:26Z

Scaroodle: /* What is Moodle's deprecation policy? */ Add a direct example even here, for the reader who knows nothing about the Moodle scheme versioning

== What is deprecation? ==

[http://en.wikipedia.org/wiki/Deprecation Deprecation], in its programming sense, is the process of taking older code and marking it as no longer being useful within the codebase, usually because it has been superseded by newer code. The deprecated code is not immediately removed from the codebase because doing so may cause regression errors.

== Why is deprecation needed? ==

In an open source project, the end use of the codebase varies. People may have customisations and plugins that depend on a function that has been targeted for deprecation. Rather than simply removing a function, we must gracefully deprecate the function over a period covered by a number of released versions.

== What is Moodle's deprecation policy? ==

* Deprecations should only be on master, not on stables (exceptions may be made for some external service integrations)
* Deprecations apply to all public APIs, classes, and files.
* Removal of a function, class, or file may only be considered after a minimum of 4 major releases since the deprecation. Example: anything deprecated in 3.2 means that it will be removed in 3.6
* All deprecations should emit debugging notices where possible
* All deprecations should be noted in the relevant upgrade.txt

== Moodle Core deprecation process ==

Once it is decided that a function should be deprecated, a two-step process should be followed.

Note that both steps should always happen as earlier as possible in the 6-months period between major releases, so all developers will have time to adjust their code and ensure it will work in the next release. Obviously, no changes will be allowed after code freeze (the APIs must remain 100% unmodified after it).

Every deprecation should be documented in the corresponding upgrade.txt files '''at least''' once, but ideally both on initial deprecation and on final removal.

=== Step 1. Immediate action ===

Deprecation affects only the current master version, in other words, the deprecation only becomes affective after the next [[Releases|major release]].

* If the function is not a member of a class (in other words, it is an independent function), it should be moved, with its PHPDoc and all comments, to ''lib/deprecatedlib.php'', which is included everywhere. If the function is a class member, it will need to be deprecated in its current location.
** Deprecated behat step definitions should be moved to lib/tests/behat/behat_deprecated.php, including a call to behat_deprecated::deprecated_message() proposing an alternative to the deprecated method.
* A debugging message should be added to the function so that, when [[:en:Debugging|developer debugging mode]] is on, attention is drawn to the deprecation. The message should state that the function being called has been deprecated. The message should help a developer whose code currently calls the function that has gone. Tell them what they should do instead.

debugging('foobar() is deprecated. Please use foobar::blah() instead.', DEBUG_DEVELOPER);

* If the deprecated function has been replaced with a new function, ideally the new function should be called from the deprecated function, so that the new functionality is used. This will make maintenance easier moving forward.
* A <tt>@deprecated</tt> tag should be added to the PHPDoc for the function description so that IDEs describing the function will note that it is deprecated, documenting which version it was deprecated in and the MDL issue associated with it. See the guidelines in [[Coding_style#.40deprecated_.28and_.40todo.29]].
* There will need to be an issue associated with the initial part of the deprecation. A second issue needs to be created to finish the job. The first issue will be linked to second issue. The second issue needs to be a sub-task of an appropriate [https://tracker.moodle.org/issues/?jql=%28summary%20~%20%22meta%22%20or%20type%20%3D%20Epic%29%20AND%20summary%20~%20%22together%20deprecated%22%20order%20by%20created&runQuery=true&clear=true deprecation META]. For example, if the current version is 3.1.2, the function will be marked as deprecated in 3.2 and should normally be removed for 3.6, so the second issue should be an issue in a deprecation epic for the 3.6 version (MDL-54740). This second issue should include instructions on how to remove the function so that when it comes time to do so, the task is trivial for any developer.
* A <tt>@todo</tt> tag can be added linking to the issues created for further action. (optional)
* A <tt>@see</tt> tag can be added to point to the new apis that can be used. (optional)
* Check the body of the function being deprecated and look for additional function calls which have no other non-deprecated uses and may also be considered for deprecation. If they belong to the same code area they can be deprecated in the same issue.

Longer deprecation periods can be considered for functions that are widely used.

=== Step 2. Final deprecation ===

* If a function has been marked as deprecated for 3.x (eg. 3.1) and set for removal at 3.x+4 (eg. 3.5), soon after the release of 3.x+3.1 (eg. 3.4.1), the 3.x+4 deprecation META will be processed. This means that the deprecated function will undergo final deprecation before 3.x+4, but only in the master version. This allows any potential regressions caused by the final deprecation of the function to be exposed as soon as possible.
* When a function undergoes final deprecation, all content of the function should be removed. In the skeleton that remains, an error statement should be included that indicates that the function cannot be used anymore. You can also direct developers to the new function(s) in this message.

throw new coding_exception('check_potential_filename() can not be used any more, please use new file API');

* All function parameters should be removed
* The content of the PHPDoc should be removed, leaving only the <tt>@deprecated</tt> tag with the notice and, optionally, the replacement information. This includes all <tt>@param</tt>, <tt>@return</tt>, and other tags, as well as the description.
* Please note that previously the final deprecation was 2 versions instead of 4. For example, functions deprecated in 2.9 are throwing exceptions starting from 3.1; however functions deprecated in 3.0 will throw exception in 3.4

== See also... ==

* [[String deprecation]]
* [[Process]]
* [[Release process]]

[[Category:Processes]]
[[Category:Core development]]

Privacy API

2018-04-09T14:15:39Z

Scaroodle: Do not use '#', codechecker will complain about it: Perl-style comments are not allowed; use "// Comment." instead

The [https://en.wikipedia.org/wiki/General_Data_Protection_Regulation General Data Protection Regulation] (GDPR) is an EU directive that looks at providing users with more control over their data and how it is processed. This regulation will come into effect on 25th of May 2018 and covers any citizen or permanent resident of the European Union. The directive will be respected by a number of other countries outside of the European Union.

To help institutions become compliant with this new regulation we are adding functionality to Moodle. This includes a number of components, amongst others these include a user’s right to:

* request information on the types of personal data held, the instances of that data, and the deletion policy for each;
* access all of their data; and
* be forgotten.

The compliance requirements also extend to installed plugins (including third party plugins). These need to also be able to report what information they store or process regarding users, and have the ability to provide and delete data for a user request.

This document describes the proposed API changes required for plugins which will allow a Moodle installation to become GDPR compliant.

Target Audience: The intended audience for this document is Moodle plugin developers, who are aiming to ensure their plugins are updated to comply with GDPR requirements coming into effect in the EU in May, 2018.

==Personal data in Moodle==

From the GDPR Spec, Article 4:

''‘personal data’ means any information relating to an identified or identifiable natural person (‘data subject’); an identifiable natural person is one who can be identified, directly or indirectly, in particular by reference to an identifier such as a name, an identification number, location data, an online identifier or to one or more factors specific to the physical, physiological, genetic, mental, economic, cultural or social identity of that natural person;''

In Moodle, we need to consider two main types of personal data; information entered by the user and information stored about the user. The key difference being that information stored about the user will have come from a source other than the user themselves. Both types of data can be used to form a profile of the individual.

The most obvious clue to finding personal data entered by the user is the presence of a userid on a database field. Any data on the record (or linked records) pertaining to that user may be deemed personal data for that user, including things like timestamps and record identification numbers. Additionally, any free text field which allows the user to enter information must also be considered to be the personal data of that user.

Data stored about the user includes things like ratings and comments made on a student submission. These may have been made by an assessor or teacher, but are considered the personal data of the student, as they are considered a reflection of the user’s competency in the subject matter and can be used to form a profile of that individual.

The sections that follow outline what you need to do as a plugin developer to ensure any personal data is advertised and can be accessed and deleted according to the GDPR requirements.

==Background==

===Architecture overview===

A new system for Privacy has been created within Moodle. This is broken down into several main parts and forms the ''core_privacy'' subsystem:

* Some metadata providers - a set of PHP interfaces to be implemented by components for that component to describe the kind of data that it stores, and the purpose for its storage;
* Some request providers - a set of PHP interfaces to be implemented by components to allow that component to act upon user requests such as the Right to be Forgotten, and a Subject Access Request; and
* A manager - a concrete class used to bridge components which implement the providers with tools which request their data.

All plugins will implement one metadata provider, and zero, one or two request providers.

The fetching of data is broken into two separate steps:

# Detecting in which Moodle contexts the user has any data; and
# Exporting all data from each of those contexts.

This has been broken into two steps to later allow administrators to exclude certain contexts from an export - e.g. for courses currently in progress.

A third component will later be added to facilitate the deletion of data within these contexts which will help to satisfy the Right to be Forgotten. This will also use the first step.

===Implementing a provider===

All plugins will need to create a concrete class which implements the relevant metadata and request providers. The exact providers you need to implement will depend on what data you store, and the type of plugin. This is covered in more detail in the following sections of the document.

In order to do so:

# You must create a class called ''provider'' within the namespace ''\your_pluginname\privacy''.
# This class must be created at ''path/to/your/plugin/classes/privacy/provider.php''.
# You must have your class implement the relevant metadata and request interfaces.

==Plugins which do not store personal data==

Many Moodle plugins do not store any personal data. This is usually the case for plugins which just add functionality, or which display the data already stored elsewhere in Moodle.

Some examples of plugin types which might fit this criteria include themes, blocks, filters, editor plugins, etc.

Plugins which cause data to be stored elsewhere in Moodle (e.g. via a subsystem call) are considered to store data.

One examples of a plugin which does not store any data would be the Calendar month block which just displays a view of the user’s calendar. It does not store any data itself.

An example of a plugin which must not use the null provider is the Comments block. The comments block is responsible for data subsequently being stored within Moodle. Although the block doesn’t store anything itself, it interacts with the comments subsystem and is the only component which knows how that data maps to a user.

===Implementation requirements===

In order to let Moodle know that you have audited your plugin, and that you do not store any personal user data, you must implement the ''\core_privacy\local\metadata\null_provider'' interface in your plugin’s provider.

The ''null_provider'' requires you to define one function ''get_reason()'' which returns the language string identifier within your component.

====Example====

''block/calendar_month/classes/privacy/provider.php''

<code php>
<?php
// …

namespace block_calendar_month\privacy;

class provider implements
// This plugin does not store any personal user data.
\core_privacy\local\metadata\null_provider {

/**
* Get the language string identifier with the component's language
* file to explain why this plugin stores no data.
*
* @return string
*/
public static function get_reason() : string {
return 'privacy:null_reason';
}
}
</code>

''block/calendar_month/lang/en/block_calendar_month.php''

<code php>
<?php

$string['privacy:null_reason'] = 'The calendar month block displays information from the Calendar, but does not effect or store any data itself. All changes are made via the Calendar.';
</code>

That’s it. Congratulations, your plugin now implements the Privacy API.

==Plugins which store personal data==

Many Moodle plugins do store some form of personal data.

In some cases this will be stored within database tables in your plugin, and in other cases this will be in one of Moodle’s core subsystems - for example your plugin may store files, ratings, comments, or tags.

Plugins which do store data will need to:

* Describe the type of data that they store;
* Provide a way to export that data; and
* Provide a way to delete that data.

Data is described via a ''metadata'' provider, and it is both exported and deleted via an implementation of a ''request'' provider.

These are both explained in the sections below.

===Describing the type of data you store===

In order to describe the type of data that you store, you must implement the ''\core_privacy\local\metadata\provider'' interface.

This interfaces requires that you define one function: ''get_metadata''.

There are several types of item to describe the data that you store. These are for:

* Items in the Moodle database;
* Items stored by you in a Moodle subsystem - for example files, and ratings; and
* User preferences stored site-wide within Moodle for your plugin

Note: All fields should include a description from a language string within your plugin.

====Example====

''mod/forum/classes/privacy/provider.php''

<code php>
<?php
// …

namespace mod_forum\privacy;
use \core_privacy\local\metadata\collection;

class provider implements
// This plugin does store personal user data.
\core_privacy\local\metadata\provider {
public static function get_metadata(collection $collection) : collection {
return $collection;
}
}
</code>

====Indicating that you store content in a Moodle subsystem====

Many plugins will use one of the core Moodle subsystems to store data.

As a plugin developer we do not expect you to describe those subsystems in detail, but we do need to know that you use them and to know what you use them for.

You can indicate this by calling the ''link_subsystem()'' method on the ''collection''.

=====Example=====

''mod/forum/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->link_subsystem(
'core_files',
'privacy:metadata:core_files'
);

return $collection;
}
</code>

''mod/forum/lang/en/forum.php''

<code php>
<?php

$string['privacy:metadata:core_files'] = 'The forum stores files which have been uploaded by the user to form part of a forum post.';
</code>

====Describing data stored in database tables====

Most Moodle plugins will store some form of user data in their own database tables.

As a plugin developer you will need to describe each database table, and each field which includes user data.

=====Example=====

''mod/forum/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->add_database_table(
'forum_discussion_subs',
[
'userid' => 'privacy:metadata:forum_discussion_subs:userid',
'discussionid' => 'privacy:metadata:forum_discussion_subs:discussionid',
'preference' => 'privacy:metadata:forum_discussion_subs:preference',

],
'privacy:metadata:forum_discussion_subs'
);

return $collection;
}
</code>

''mod/forum/lang/en/forum.php''

<code php>
<?php

$string['privacy:metadata:forum_discussion_subs'] = 'Information about the subscriptions to individual forum discussions. This includes when a user has chosen to subscribe to a discussion, or to unsubscribe from one where they would otherwise be subscribed.';
$string['privacy:metadata:forum_discussion_subs:userid'] = 'The ID of the user with this subscription preference.';
$string['privacy:metadata:forum_discussion_subs:discussionid'] = 'The ID of the discussion that was subscribed to.';
$string['privacy:metadata:forum_discussion_subs:preference'] = 'The start time of the subscription.';
</code>

====Indicating that you store site-wide user preferences====

Many plugins will include one or more user preferences. Unfortunately this is one of Moodle’s older components and many of the values stored are not pure user preferences. Each plugin should be aware of how it handles its own preferences and is best placed to determine whether they are site-wide preferences, or per-instance preferences.

Whilst most of these will have a fixed name (e.g. ''filepicker_recentrepository''), some will include a variable of some kind (e.g. ''tool_usertours_tour_completion_time_2''). Only the general name needs to be indicated rather than one copy for each preference.

Also, these should only be ''site-wide'' user preferences which do not belong to a specific Moodle context.

In the above examples:

* Preference ''filepicker_recentrepository'' belongs to the file subsystem, and is a site-wide preference affecting the user anywhere that they view the filepicker.
* Preference ''tool_usertours_tour_completion_time_2'' belongs to user tours. User tours are a site-wide feature which can affect many parts of Moodle and cross multiple contexts.

In some cases a value may be stored in the preferences table but is known to belong to a specific context within Moodle. In these cases they should be stored as metadata against that context rather than as a site-wide user preference.

You can indicate this by calling the ''add_user_preference()'' method on the ''collection''.

Any plugin providing user preferences must also implement the ''\core_privacy\local\request\preference_provider''.

=====Example=====

''admin/tool/usertours/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->add_user_preference('tool_usertours_tour_completion_time,
'privacy:metadata:preference:tool_usertours_tour_completion_time');

return $collection;
}
</code>

''admin/tool/usertours/lang/en/tool_usertours.php''

<code php>
<?php

$string['privacy:metadata:tool_usertours_tour_completion_time'] = 'The time that a specific user tour was last completed by a user.';
</code>

====Indicating that you export data to an external location====

Many plugins will interact with external systems - for example cloud-based services. Often this external location is configurable within the plugin either at the site or the instance level.

As a plugin developer you will need to describe each ''type'' of target destination, alongside a list of each exported field which includes user data.
The ''actual'' destination does not need to be described as this can change based on configuration.

You can indicate this by calling the ''link_external_location()'' method on the collection.

=====Example=====

''mod/lti/classes/privacy/provider.php''

<code php>
public static function get_metadata(collection $collection) : collection {

$collection->link_external_location('lti_client', [
'userid' => 'privacy:metadata:lti_client:userid',
'fullname' => 'privacy:metadata:lti_client:fullname',
], 'privacy:metadata:lti_client');

return $collection;
}
</code>

''mod/lti/lang/en/lti.php''

<code php>
<?php

$string['privacy:metadata:lti_client'] = 'In order to integrate with a remote LTI service, user data needs to be exchanged with that service.';
$string['privacy:metadata:lti_client:userid'] = 'The userid is sent from Moodle to allow you to access your data on the remote system.';
$string['privacy:metadata:lti_client:fullname'] = 'Your full name is sent to the remote system to allow a better user experience.';
</code>

===Providing a way to export user data===

In order to export the user data that you store, you must implement the relevant request provider.

We have named these request providers because they are called in response to a specific request from a user to access their information.

There are several different types of request provider, and you may need to implement several of these, depending on the type and nature of your plugin.

Broadly speaking plugins will fit into one of the following categories:

* Plugins which are a subplugin of another plugin. Examples include ''assignsubmission'', ''atto'', and ''datafield'';
* Plugins which are typically called by a Moodle subsystem. Examples include ''qtype'', and ''profilefield'';
* All other plugins which store data.

Most plugins will fit into this final category, whilst other plugins may fall into several categories.
Plugins which ''define'' a subplugin will also be responsible for collecting this data from their subplugins.

A final category exists - plugins which store user preferences. In some cases this may be the ''only'' provider implemented.

====Standard plugins which store data====

A majority of Moodle plugins will fit into this category and will be required to implement the ''\core_privacy\local\request\plugin\provider'' interface. This interface requires that you define two functions:

* ''get_contexts_for_userid'' - to explain where data is held within Moodle for your plugin; and
* ''export_user_data'' - to export a user’s personal data from your plugin.

These APIs make use of the Moodle ''context'' system to hierarchically store this data.

====Retrieving the list of contexts====

Contexts are retrieved using the ''get_contexts_for_userid'' function which takes the ID of the user being fetched, and returns a list of contexts in which the user has any data.

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The list of contexts used in this plugin.
*/
public static function get_contexts_for_userid(int $userid) : contextlist {}
</code>

The function returns a ''\core_privacy\local\request\contextlist'' which is used to keep a set of contexts together in a fixed fashion.

Because a Subject Access Request covers ''every'' piece of data that is held for a user within Moodle, efficiency and performance is highly important. As a result, contexts are added to the ''contextlist'' by defining one or more SQL queries which return just the contextid. Multiple SQL queries can be added as required.

Many plugins will interact with specific subsystems and store data within them.
These subsystems will also provide a way in which to link the data that you have stored with your own database tables.
At present these are still a work in progress and only the ''core_ratings'' subsystem includes this.

=====Basic example=====

The following example simply fetches the contextid for all forums where a user has a single discussion (note: this is an incomplete example):

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The list of contexts used in this plugin.
*/
public static function get_contexts_for_userid(int $userid) : contextlist {
$contextlist = new \core_privacy\local\request\contextlist();

$sql = "SELECT c.id
FROM {context} c
INNER JOIN {course_modules} cm ON cm.id = c.instanceid AND c.contextlevel = :contextlevel
INNER JOIN {modules} m ON m.id = cm.module AND m.name = :modname
INNER JOIN {forum} f ON f.id = cm.instance
LEFT JOIN {forum_discussions} d ON d.forum = f.id
WHERE (
d.userid = :discussionuserid
)
";

$params = [
'modname' => 'forum',
'contextlevel' => CONTEXT_MODULE,
'discussionuserid' => $userid,
];

$contextlist->add_from_sql($sql, $params);
}
</code>

=====More complete example=====

The following example includes a link to core_rating.
It will find any forum, forum discussion, or forum post where the user has any data, including:

* Per-forum digest preferences;
* Per-forum subscription preferences;
* Per-forum read tracking preferences;
* Per-discussion subscription preferences;
* Per-post read data (if a user has read a post or not); and
* Per-post rating data.

In the case of the rating data, this will include any post where the user has rated the post of another user.

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The list of contexts used in this plugin.
*/
public static function get_contexts_for_userid(int $userid) : contextlist {
$ratingsql = \core_rating\privacy\provider::get_sql_join('rat', 'mod_forum', 'post', 'p.id', $userid);
// Fetch all forum discussions, and forum posts.
$sql = "SELECT c.id
FROM {context} c
INNER JOIN {course_modules} cm ON cm.id = c.instanceid AND c.contextlevel = :contextlevel
INNER JOIN {modules} m ON m.id = cm.module AND m.name = :modname
INNER JOIN {forum} f ON f.id = cm.instance
LEFT JOIN {forum_discussions} d ON d.forum = f.id
LEFT JOIN {forum_posts} p ON p.discussion = d.id
LEFT JOIN {forum_digests} dig ON dig.forum = f.id
LEFT JOIN {forum_subscriptions} sub ON sub.forum = f.id
LEFT JOIN {forum_track_prefs} pref ON pref.forumid = f.id
LEFT JOIN {forum_read} hasread ON hasread.forumid = f.id
LEFT JOIN {forum_discussion_subs} dsub ON dsub.forum = f.id
{$ratingsql->join}
WHERE (
p.userid = :postuserid OR
d.userid = :discussionuserid OR
dig.userid = :digestuserid OR
sub.userid = :subuserid OR
pref.userid = :prefuserid OR
hasread.userid = :hasreaduserid OR
dsub.userid = :dsubuserid OR
{$ratingsql->userwhere}
)
";

$params = [
'modname' => 'forum',
'contextlevel' => CONTEXT_MODULE,
'postuserid' => $userid,
'discussionuserid' => $userid,
'digestuserid' => $userid,
'subuserid' => $userid,
'prefuserid' => $userid,
'hasreaduserid' => $userid,
'dsubuserid' => $userid,
];
$params += $ratingsql->params;

$contextlist = new \core_privacy\local\request\contextlist();
$contextlist->add_from_sql($sql, $params);

return $contextlist;

}
</code>

====Exporting user data====

After determining where in Moodle your plugin holds data about a user, the ''\core_privacy\manager'' will then ask your plugin to export all user data for a subset of those locations.

This is achieved through use of the ''export_user_data'' function which takes the list of approved contexts in a ''\core_privacy\local\request\approved_contextlist'' object.

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Export all user data for the specified user, in the specified contexts, using the supplied exporter instance.
*
* @param approved_contextlist $contextlist The approved contexts to export information for.
*/
public static function export_user_data(approved_contextlist $contextlist) {}
</code>

The ''approved_contextlist'' includes both the user record, and a list of contexts, which can be retrieved by either processing it as an Iterator, or by calling ''get_contextids()'' or ''get_contexts()'' as required.

Data is exported using a ''\core_privacy\local\request\content_writer'', which is described in further detail below.

===Plugins which store user preferences===

Many plugins store a variety of user preferences, and must therefore export them.

Since user preferences are a site-wide preference, these are exported separately to other user data.
In some cases the only data present is user preference data, whilst in others there is a combination of user-provided data, and user preferences.

Storing of user preferences is achieved through implementation of the ''\core_privacy\local\request\preference_provider'' interface which defines one required function -- ''export_user_preferences''.

====Example====

''mod/forum/classes/privacy/provider.php''

<code php>
/**
* Export all user preferences for the plugin.
*
* @param int $userid The userid of the user whose data is to be exported.
*/
public static function export_user_preferences(int $userid) {
$markasreadonnotification = get_user_preference('markasreadonnotification', null, $userid);
if (null !== $markasreadonnotification) {
switch ($markasreadonnotification) {
case 0:
$markasreadonnotificationdescription = get_string('markasreadonnotificationno', 'mod_forum');
break;
case 1:
default:
$markasreadonnotificationdescription = get_string('markasreadonnotificationyes', 'mod_forum');
break;
}
writer::export_user_preference('mod_forum', 'markasreadonnotification', $markasreadonnotification, $markasreadonnotificationdescription);
}
}
</code>

===Plugins which define a subplugin===

Many plugin types are also able to define their own subplugins and will need to define a contract between themselves and their subplugins in order to fetch their data.

This is required as the parent plugin and the child subplugin should be separate entities and the parent plugin must be able to function if one or more of its subplugins are uninstalled.

The parent plugin is responsible for defining the contract, and for interacting with its subplugins, though we intend to create helpers to make this easier.

The parent plugin should define a new interface for each type of subplugin that it defines. This interface should extend the ''\core_privacy\local\request\plugin\subplugin_provider'' interface.

====Example====

The following example defines the contract that assign submission subplugins may be required to implement.

The assignment module is responsible for returning the contexts of all assignments where a user has data, but in some cases it is unaware of all of those cases - for example if a Teacher comments on a student submission it may not be aware of these as the information about this interaction may not be stored within its own tables.

''mod/assign/privacy/assignsubmission_provider.php''

<code php>
<?php
// …

namespace mod_assign\privacy;
use \core_privacy\local\metadata\collection;

interface assignsubmission_provider extends
// This Interface defines a subplugin.
\core_privacy\local\request\subplugin_provider {

/**
* Get the SQL required to find all submission items where this user has had any involvements.
*
* @param int $userid The user to search.
* @return \stdClass Object containing the join, params, and where used to select a these records from the database.
*/
public static function get_items_with_user_interaction(int $userid) : \stdClass ;

/**
* Export all relevant user submissions information which match the combination of userid and attemptid.
*
* @param int $userid The user to search.
* @param \context $context The context to export this submission against.
* @param array $subcontext The subcontext within the context to export this information
* @param int $attid The id of the submission to export.
*/
public static function export_user_submissions(int $userid, \context $context, array $subcontext, int $attid) ;

}
</code>

===Plugins which are subplugins to another plugin===

If you are developing a sub-plugin of another plugin, then you will have to look at the relevant plugin in order to determine the exact contract.

Each subplugin type should define a new interface which extends the ''\core_privacy\local\request\plugin\subplugin_provider'' interface and it is up to the parent plugin to define how they will interact with their children.

The principles remain the same, but the exact implementation will differ depending upon requirements.

''mod/pluginname/classes/privacy/provider.php''

<code php>
<?php
// …
namespace assignsubmission\onlinetext;

class provider implements
// This plugin does store personal user data.
\core_privacy\local\metadata\provider,

// This plugin is a subplugin of assign and must meet that contract.
\mod_assign\privacy\assignsubmission_provider {
}
</code>

===Plugins which are typically called by a Moodle subsystem===

There are a number of plugintypes in Moodle which are typically called by a specific Moodle subsystem.

Some of these are ''only'' called by that subsystem, for example plugins which are of the ''plagiarism'' plugintype should never be called directly, but are always invoked via the ''core_plagiarism'' subsystem.

Conversely, there maybe other plugintypes which can be called both via a subsystem, and in some other fashion. We are still determining whether any plugintypes currently fit this pattern.

If you are developing a plugin which belongs to a specific subsystem, then you will have to look at the relevant plugin in order to determine the exact contract.

Each subsystem will define a new interface which extends the ''\core_privacy\local\request\plugin\subsystem_provider'' interface and it is up to that subsystem to define how they will interact with those plugins.

The principles remain the same, but the exact implementation will differ depending upon requirements.

''plagiarism/detectorator/classes/privacy/provider.php''

<code php>
<?php
// …
namespace plagiarism_detectorator\privacy;

class provider implements
// This plugin does export personal user data.
\core_privacy\local\metadata\provider,

// This plugin is always linked against another activity module via the Plagiarism API.
\core_plagiarism\privacy\plugin_provider {
}
</code>

===Exporting data===

Any plugin which stores data must also export it.

To cater for this the privacy API includes a ''\core_privacy\local\request\content_writer'', which defines a set of functions to store different types of data.

Broadly speaking data is broken into the following types:

* Data - this is the object being described. For example the post content in a forum post;
* Related data - this is data related to the object being stored. For example, ratings of a forum post;
* Metadata - This is metadata about the main object. For example whether you are subscribed to a forum discussion;
* User preferences - this is data about a site-wide preference;
* Files - Any files that you are stored within Moodle on behalf of this plugin; and
* Custom files - For custom file formats - e.g. a calendar feed for calendar data. These should be used sparingly.

Each piece of data is stored against a specific Moodle ''context'', which will define how the data is structured within the exporter.
Data, and Related data only accept the ''stdClass'' object, whilst metadata should be stored as a set of key/value pairs which include a description.

In some cases the data being stored belongs within an implicit structure. For example, one forum has many forum discussions, which each have a number of forum posts. This structure is represented by an ''array'' referred to as a ''subcontext''.

The ''content_writer'' must ''always'' be called with a specific context, and can be called as follows:

''mod/forum/classes/privacy/provider.php''

<code php>
<?php
// …
use \core_privacy\local\request\writer;

writer::with_context($context)
->export_data($subcontext, $post)
->export_area_files($subcontext, 'mod_forum', 'post', $post->id)
->export_metadata($subcontext, 'postread', (object) ['firstread' => $firstread], new \lang_string('privacy:export:post:postread'));
</code>

Any text field which supports Moodle files must also be rewritten:

''mod/forum/classes/privacy/provider.php''

<code php>
<?php
// …
use \core_privacy\local\request\writer;

writer::with_context($context)
->rewrite_pluginfile_urls($postarea, 'mod_forum', 'post', $post->id, $post->message);

</code>

===Providing a way to delete user data===

Deleting user data is also implemented in the request interface. There are two methods that need to be created. The first one to remove all user data from a context, the other to remove user data for a specific user in a list of contexts.

====Delete for a context====

A context is given and all user data (for all users) is to be deleted from the plugin. This will be called when the retention period for the plugin has expired to adhere to the privacy by design requirement.�

''mod/choice/classes/privacy/provider.php''

<code php>
public static function delete_data_for_all_users_in_context(deletion_criteria $criteria) {
global $DB;
$context = $criteria->get_context();
if (empty($context)) {
return;
}
$instanceid = $DB->get_field('course_modules', 'instance', ['id' => $context->instanceid], MUST_EXIST);
$DB->delete_records('choice_answers', ['choiceid' => $instanceid]);
}
</code>

====Delete personal information for a specific user and context(s)====

An ''approved_contextlist'' is given and user data related to that user should either be completely deleted, or overwritten if a structure needs to be maintained. This will be called when a user has requested the right to be forgotten. All attempts should be made to delete this data where practical while still allowing the plugin to be used by other users.

''mod/choice/classes/privacy/provider.php''

<code php>
public static function delete_data_for_user(approved_contextlist $contextlist) {
global $DB;

if (empty($contextlist->count())) {
return;
}
$userid = $contextlist->get_user()->id;
foreach ($contextlist->get_contexts() as $context) {
$instanceid = $DB->get_field('course_modules', 'instance', ['id' => $context->instanceid], MUST_EXIST);
$DB->delete_records('choice_answers', ['choiceid' => $instanceid, 'userid' => $userid]);
}
}
</code>

==See also==

* [[Subject Access Request FAQ]]
* [[:en:GDPR|GDPR]] in the user documentation

[[Category:GDPR]]
[[Category:API]]

Moodle 3.4 release notes

2018-03-07T23:28:58Z

Scaroodle: /* Server requirements */ OSes not properly updated could prevent the connection to SSL/TLS secured resources due to old/missing root CA certificates (https://moodle.org/mod/forum/discuss.php?d=366514#p1478917)

[[Releases]] > {{FULLPAGENAME}}

Release date: 13 November 2017

Here is [https://tracker.moodle.org/issues/?jql=project%20%3D%20mdl%20AND%20resolution%20%3D%20fixed%20AND%20fixVersion%20in%20(3.4)%20ORDER%20BY%20priority%20DESC the full list of fixed issues in 3.4].

See our [https://docs.moodle.org/34/en/New_features New Features page] for a more user-friendly introduction to Moodle 3.4 with screenshots.

If you are upgrading from previous version, make sure you read the [https://docs.moodle.org/34/en/Upgrading Upgrading] documentation.

==Server requirements==

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

* Moodle upgrade: Moodle 3.0 or later (if upgrading from earlier versions, you must upgrade to 3.0.10 as a first step)
* PHP version: minimum PHP 7.0.0 ''Note: minimum PHP version has increased since Moodle 3.3''. PHP 7.1.x and 7.2.x are supported too. PHP 7.x could have some [https://docs.moodle.org/dev/Moodle_and_PHP7#Can_I_use_PHP7_yet.3F engine limitations].
* PHP extension '''intl''' is now required in Moodle 3.4 (it was recommended in 2.0 onwards)

=== Database requirements ===

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

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.3
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.5.31
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 5.5.31
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2008
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 10.2
| Latest
|}

==Client requirements==

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

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

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date. https://whatbrowser.org

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

==Major features==

===Calendar improvements===

* MDL-59333 - Calendar Improvements
* MDL-1322 - Calendar entries in monthly view should include course shortname
* MDL-59382 - Create calendar event quick-add
* MDL-59390 - Add navigation of all calendar views without page reload
* MDL-59394 - Add support for drag and drop of calendar events
* MDL-59386 - Add support for creation and update of calendar events using a modal dialogue
* MDL-59890 - Add support for calendar events at the category level

===Management of course participants===

* MDL-59290 - Merge Course Participants and Enrolled Users pages
* MDL-59564 - Add bulk editing of enrolment status/dates for users in the course participants page
* MDL-59364 - Remove the "Brief / User Details" functionality from the participants page
* MDL-59365 - Enrol Users button on participants page
* MDL-59366 - Add filter controls to the participants page to allow custom filtering
* MDL-59367 - Add a roles column to participants page
* MDL-59368 - Add a groups column to the participants page
* MDL-59369 - Add a status column to the participants page
* MDL-59436 - Remove the columns from the participants page that are not in showuseridentity
* MDL-59821 - Add "Proceed to course content" to participants page

===Other highlights===

* MDL-57791 - Implement analytics engine in Moodle
* MDL-59313 - Add links and a drop down to navigate between activities
* MDL-37361 - Allow teachers to mark activities as completed

===Backup, restore and import===

* MDL-35429 - Correct the permissions required to download and restore course automated backups
* MDL-9367 - Restore with roll forward changes dates for user data
* MDL-59518 - Restore date should not roll for user created data - Core components

===Global search===

* MDL-55356 - Index contents of the restored courses
* MDL-59523 - Course reset doesn't always shift dates
* MDL-58957 - Global search: Make it possible to search blocks
* MDL-59039 - Global search: Allow partial indexing (in scheduled task)

===Authentication===

* MDL-30634 - Assign arbitrary system roles via LDAP sync
* MDL-58544 - Add option to trust email of an OAuth provider
* MDL-59844 - Enable OAuth 2 token-based authentication for requests in webdav_client
* MDL-59459 - Global Search: Increase file indexing coverage
* MDL-59913 - Global search: Allow search of non-enrolled courses

===Functional changes===

* MDL-55358 - LIS Group Variables support in LTI
* MDL-36501 - Should have checkbox for extra credit when you add a grade item
* MDL-28574 - Web services: Manage tokens page should show tokens for all users
* MDL-26976 - Display space used in My Private Files
* MDL-35668 - Performance improvement in Server files repository
* MDL-49398 - Performance improvement due to Role definition caching & accesslib refactoring
* MDL-60002 - Assignment grading: Adding back "Save and show next"
* MDL-58889 - Make section titles and course titles more accessible in Boost
* MDL-57455 - Allow to tag database entries
* MDL-36985 - Assignment: automatically remove embedded files that are no longer linked from submission text. Reduce the size of "Download all submissions"
* MDL-59702 - Lesson overview report does not respect value of showuseridentity setting
* MDL-59460 - Forum: make Subscription mode setting configurable

===For administrators===

Please read carefully: [https://docs.moodle.org/34/en/Upgrading#Possible_issues_that_may_affect_you_in_Moodle_3.4 Possible issues that may affect you in Moodle 3.4]

* MDL-42834 - Deprecate loginhttps. Sites that used to use this setting will now be served via https always
* MDL-46269 - Tool to [https://docs.moodle.org/34/en/HTTPS_conversion_tool convert http embedded content to https] where available
* MDL-58388 - Let the admin control if the course end date form field in course settings is enabled by default
* MDL-60211 - New filters for User Tours
* MDL-59123 - Compile SCSS files on the command-line
* MDL-58567 - Upgrade: Show upgrade times
* MDL-55652 - Missing index on (timemodified) in grade_items_history table and several other grade history tables. This will increase performance of various reports but may also slow down Moodle upgrade
* MDL-60094 - Add CLI script to kill all sessions
* MDL-59495 - Register and publish courses with moodle.net only, remove support for alternative hubs
* MDL-59206 - Trigger an event in add_to_config_log function
* MDL-57115 - Move "Messages" block out from the standard Moodle distribution
* MDL-57734 - SEO - Create admin setting to be able to enable or disable search engine indexing for sites with forcelogin
* MDL-60309 - Boost: Add a setting for background image
* MDL-56751 - Create new security setting to configure the expiration time of tokens created via login/token.php or tool/mobile/launch.php

===Security issues===

* [https://moodle.org/mod/forum/discuss.php?d=361784 MSA-17-0021] Students can find out email addresses of other students in the same course

This list only includes security issues fixed after 3.3.2 release. Refer to other [[Releases|release notes]] for security issues fixed in earlier releases.

===For developers===

* MDL-60611 - Upgrade PHPUnit to 6.4 to ensure compatibility with PHP 7.2 - [https://docs.moodle.org/dev/Writing_PHPUnit_tests#Upgrading_unit_tests_to_work_with_Moodle_3.4_and_up_.28PHPUnit_6.29 may require changes in unittests].
* MDL-58948 - Compatibility with chrome mink driver
* MDL-53169 - Provide a way to retrieve all courses a user can potentially access.
* MDL-59459 - Global Search: Increase file indexing coverage
* MDL-58957 - Global search: Make it possible to search blocks. See the new [https://docs.moodle.org/dev/Search_API#Base_class \core_search\base_block class].
* MDL-53240 - [[lib/formslib.php Form Definition#filetypes|Form element]] and admin setting type to choose file types and type groups
* MDL-53848 - Formslib - add function to $mform that makes it possible to hide form elements dependent on selected values
* MDL-60234 - Add possibility to disable admin warning if a development libs directory exists
* MDL-57886 - Plagiarism: onlinetext submission should pass raw submissiontext to plagiarism get_links()

==== Upgrading plugins ====

'''1. Check for changes in core APIs'''

Read lib/upgrade.txt to check for the deprecations and core API changes, make sure you applied them to your plugin. Note that entries there are not sorted by priority but rather by integration time. Below is the list of upgrade.txt files that contain information about upgrading from Moodle 3.3 to Moodle 3.4 (note that if you upgrade from earlier versions there may be more files):

* [https://raw.githubusercontent.com/moodle/moodle/master/lib/upgrade.txt lib/upgrade.txt] changes to various core APIs, deprecations, functions removal
* [https://raw.githubusercontent.com/moodle/moodle/master/calendar/upgrade.txt calendar/upgrade.txt] changes to Calendar API
* [https://raw.githubusercontent.com/moodle/moodle/master/search/upgrade.txt search/upgrade.txt] changes to Global search API
* [https://raw.githubusercontent.com/moodle/moodle/master/webservice/upgrade.txt webservice/upgrade.txt] changes to WebServices API

'''2. Check for changes in the API of your plugin type'''

Below is the list of plugin types that had API changes between Moodle 3.3 and 3.4:

* [https://raw.githubusercontent.com/moodle/moodle/master/blocks/upgrade.txt blocks/upgrade.txt] Block plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/dataformat/upgrade.txt dataformat/upgrade.txt] Dataformat plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/enrol/upgrade.txt enrol/upgrade.txt] Enrolment method plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/mod/upgrade.txt mod/upgrade.txt] Activity module plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/plagiarism/upgrade.txt plagiarism/upgrade.txt] Plagiarism plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/repository/upgrade.txt repository/upgrade.txt] Repository plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/theme/upgrade.txt theme/upgrade.txt] Themes
* [https://raw.githubusercontent.com/moodle/moodle/master/user/profile/field/upgrade.txt user/profile/field/upgrade.txt] User profile fields

'''3. Check for changes in the depended plugins'''

If your plugin depends on another plugin or calls methods from another plugin, read upgrade.txt in this plugin directory (if it exists). Below is the list of standard plugins that had changes between Moodle 3.3 and 3.4:

[https://raw.githubusercontent.com/moodle/moodle/master/admin/tool/log/store/database/upgrade.txt logstore_database],
[https://raw.githubusercontent.com/moodle/moodle/master/admin/tool/mobile/upgrade.txt tool_mobile],
[https://raw.githubusercontent.com/moodle/moodle/master/auth/ldap/upgrade.txt auth_ldap],
[https://raw.githubusercontent.com/moodle/moodle/master/blocks/calendar_upcoming/upgrade.txt block_calendar_upcoming],
[https://raw.githubusercontent.com/moodle/moodle/master/lib/editor/atto/upgrade.txt editor_atto],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/assign/upgrade.txt mod_assign],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/data/upgrade.txt mod_data],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/forum/upgrade.txt mod_forum],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/glossary/upgrade.txt mod_glossary],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/lesson/upgrade.txt mod_lesson],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/lti/upgrade.txt mod_lti],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/workshop/upgrade.txt mod_workshop],
[https://raw.githubusercontent.com/moodle/moodle/master/theme/boost/upgrade.txt theme_boost]

'''4. Do a smoke test of your plugin with developer debugging mode'''

'''5. Run all behat and phpunit tests'''

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

[[Category:Release notes]]
[[Category:Moodle 3.4]]

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

Git for developers

2017-10-24T22:04:07Z

Scaroodle: Replaced "nasties" according to https://tracker.moodle.org/browse/MDL-57976?focusedCommentId=485633&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-485633

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/bash
git fetch upstream
for BRANCH in MOODLE_{19..33}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:refs/heads/$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-short-description-of-the-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push origin MDL-xxxxx-short-description-of-the-bug

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase --interactive''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it, for example: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-short-description-of-the-bug" you will get an error message suggesting you to force push.
To force push the changed commits use:

git push -f origin MDL-xxxxx-short-description-of-the-bug

If an error occurs because you are still using the git protocol (read only), use this command :

git remote set-url origin https://github.com/<user.name>/moodle.git

A prompt will ask for your credentials, if you previously setup your SSH public key you can also use this one :

git remote set-url origin git@github.com:<user.name>/moodle.git

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the master. The command (2) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (3) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]

[[Category:Git]]

[[ja:開発者用Git]]

Git for developers

2017-10-24T22:00:33Z

Scaroodle: Provide an example according to https://tracker.moodle.org/browse/MDL-57976?focusedCommentId=485633&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-485633

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/bash
git fetch upstream
for BRANCH in MOODLE_{19..33}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:refs/heads/$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-nasty-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push origin MDL-xxxxx-nasty-bug

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase --interactive''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it, for example: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-nasty-bug" you will get an error message suggesting you to force push.
To force push the changed commits use:

git push -f origin MDL-xxxxx-nasty-bug

If an error occurs because you are still using the git protocol (read only), use this command :

git remote set-url origin https://github.com/<user.name>/moodle.git

A prompt will ask for your credentials, if you previously setup your SSH public key you can also use this one :

git remote set-url origin git@github.com:<user.name>/moodle.git

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the master. The command (2) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (3) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]

[[Category:Git]]

[[ja:開発者用Git]]

Git for developers

2017-10-24T07:25:16Z

Scaroodle: Specified the actual type of rebase required here. A first quick review to catch what describe in https://tracker.moodle.org/browse/MDL-57976?focusedCommentId=485633&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-485633

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/bash
git fetch upstream
for BRANCH in MOODLE_{19..33}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:refs/heads/$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-nasty-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push origin MDL-xxxxx-nasty-bug

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase --interactive''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-nasty-bug" you will get an error message suggesting you to force push.
To force push the changed commits use:

git push -f origin MDL-xxxxx-nasty-bug

If an error occurs because you are still using the git protocol (read only), use this command :

git remote set-url origin https://github.com/<user.name>/moodle.git

A prompt will ask for your credentials, if you previously setup your SSH public key you can also use this one :

git remote set-url origin git@github.com:<user.name>/moodle.git

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the master. The command (2) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (3) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]

[[Category:Git]]

[[ja:開発者用Git]]

Automatic class loading

2017-05-25T20:36:39Z

Scaroodle: Fixed typo

{{Moodle 2.6}}

This document describes how to use the functionality of the automatic classloader provided by Moodle.

==Class naming==

To be discoverable by the Moodle automatic classloader, classes must adhere to the following class naming rules:
* [[Frankenstyle]] Prefixes
** Core classes must start with the prefix ''core_''.
** Plugin class names must start with names such as ''plugintype_pluginname_''. For example: ''mod_forum_'' (in the example of /mod/forum)
* One class file for each class
* Class file names must be class name without Frankenstyle prefix
** e.g. Class '''mod_forum_some_class''' is stored in file '''mod/forum/classes/some_class.php'''
** e.g. Class '''core_frankenstyle''' class is stored in '''lib/classes/frankenstyle.php'''

==Class files and locations==

The Moodle automatic classloader looks for classes only in specific locations (all caps represents a symbolic name, replace it with a real location)
* Core classes
** '''/lib/classes/''' and its subdirectories
** '''SUBSYSTEMDIR/classes/''' and its subdirectories
*** The list of subsystems and their respective directories can be found in code (/lib/classes/component.php, function fetch_subsystems)
* Plugin classes
** /PLUGIN/DIR/classes and its subdirectories

==Code Examples==

Example of autoloaded class in forum module:

<code php>
<?php
// file mod/forum/classes/some_class.php

class mod_forum_some_class {

}
</code>

<code php>
<?php
// file mod/forum/lib.php

// no require_once() necessary here

$instance = new mod_forum_some_class();

</code>

<code php>

<?php

// in any file

if (class_exists('mod_forum_some_class')) {
// do something
}
</code>

==Namespaces==

PHP namespaces are designed to improve code organisation in your projects. Directory structure in classes/ is matching the namespace structure.

Example:

<code php>
<?php

namespace core\event;

// file lib/classes/event/base.php

class base {
}
</code>

<code php>
<?php

namespace mod_forum\event;

// file mod/forum/classes/event/post_read.php

class post_read extends \core\event\base {

}
</code>

<code php>
<?php

// in any file

\mod_forum\event\post_read::create($post->id, ...)->trigger();

</code>

Note there are restrictions on valid choices for the first and second level namespaces in Moodle - see [[Coding_style#Namespaces]] for more info.

==Backwards compatibility==
There are no know issues that could cause backwards incompatibility, however it is strongly recommended to use the classes subdirectory only for classes that are included automatically.

==Performance and developer mode==

Class autoloading improves performance and reduces memory footprint. Location of all classes is automatically stored in class map cache, the cache is updated automatically before upgrade or installation, during cache reset and in developer mode.

There is only one inconvenience - if you add new class or remove it you need to do one of the following:
* visit yourserver/admin/index.php
* purge caches
* or add '''$CFG->debug = (E_ALL | E_STRICT);''' to your config.php

Otherwise the new class would not be found.

==See also==

* [[Frankenstyle]]
* [[Automatic Class Loading Proposal]]

[[Category:Plugins]]

Global search

2016-03-04T22:01:08Z

Scaroodle: /* Linux */ This section is actually for a Debian/Ubuntu based Linux distro.

= Installation =

To use Solr as Moodle's search engine you need the PHP Solr extension and a Solr server.

== PHP Solr extension ==

You need PHP Solr extension installed. Use PECL Solr Extension 1.x for Solr Server 3.x, or use PECL Solr 2.x for Solr Server 4.0+.

You can download the official latest versions from [http://pecl.php.net/package/solr](http://pecl.php.net/package/solr)

Basic installation steps (using apache web server):

=== Linux (Debian/Ubuntu) ===

sudo apt-get install libpcre3-dev libxml2-dev libcurl4-openssl-dev
sudo pecl install solr
sudo service apache2 restart
sudo sh -c "echo 'extension=solr.so' > /etc/php5/apache2/conf.d/solr.ini"
sudo sh -c "echo 'extension=solr.so' > /etc/php5/cli/conf.d/solr.ini"

=== OSX using macports ===

sudo port install apache-solr4
sudo port install php54-solr

=== Windows ===

Install the pecl package as usual. Sorry it has not been tested yet.

== Solr server ==

The following snippet (feel free to copy & paste into a .sh script with execution permissions) will download Solr 5.4.1 in the current directory, start the solr server and create an index in it named '''moodle''' to add moodle data to it.

#!/bin/bash
set -e
SOLRVERSION=5.4.1
SOLRNAME=solr-$SOLRVERSION
SOLRTAR=$SOLRNAME'.tgz'
INDEXNAME=moodle
if [ -d $SOLRNAME ]; then
echo "Error: Directory $SOLRNAME already exists, remove it before starting the setup again."
exit 1
fi
if [ ! -f $SOLRTAR ]; then
wget http://apache.mirror.digitalpacific.com.au/lucene/solr/$SOLRVERSION/$SOLRTAR
fi
tar -xvzf $SOLRTAR
cd $SOLRNAME
bin/solr start
bin/solr create -c $INDEXNAME
# After setting it up and creating the index use:
# - "/yourdirectory/solrdir/bin/solr start" from CLI to start the server
# - "/yourdirectory/solrdir/bin/solr stop" from CLI to stop the server.

= Setup =

# Go to '''Site administration -> Plugins -> Search -> Manage global search'''
# Follow '''Search setup''' steps to complete the setup process. Basically you have to:
## Enable global search
## Set '''Solr''' as search engine and tick all search areas checkboxes
## Go to '''Site administration -> Plugins -> Search -> Solr''' and set '''Host name''' to localhost, '''Port''' to 8983 and '''Index name''' to 'moodle' (the name of the index in Solr)

= Indexing =

Once global search is enabled a new task will be running through cron, although you can force documents indexing by:

# Going to '''Reports -> Global search info'''
# Tick '''Index all site contents''' and press '''Execute'''

or

* Executing the following task from CLI

php admin/tool/task/cli/schedule_task.php --execute="\\core\\task\\search_task"

= Querying =

# Hover the search icon in the navigation bar, type your query and press '''Enter'''

or

# Add '''Global search''' block somewhere
# Type your query and press '''Search'''

Blocks

2016-01-05T17:32:06Z

Scaroodle: Removed the just added mention to the "NEWMODULE" docs to prevent confusing newbies. Thanks to David Mudrák for the support!

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned below, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for core blocks. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability is not required. The following is the capabilities array and how it should look for any new blocks.

<code php>
<?php
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with the capabilities we created and any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).

The capabilities added above need descriptions for pages that allow setting of capabilities. These should also be added to the language file.

<code php>
<?php
$string['pluginname'] = 'Simple HTML block';
$string['simplehtml'] = 'Simple HTML';
$string['simplehtml:addinstance'] = 'Add a new simple HTML block';
$string['simplehtml:myaddinstance'] = 'Add a new simple HTML block to the My Moodle page';
</code>

=== version.php ===

This file will hold version information for the plugin, along '''with other advanced parameters''' (not covered here - see [[version.php]] if you want '''more details''').

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
<?php
$plugin->component = 'block_simplehtml'; // Recommended since 2.0.2 (MDL-26035). Required since 3.0 (MDL-48494)
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the full [[Frankenstyle|frankenstyle]] component name in the form of ''plugintype_pluginname'' and the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also we don't include a closing "?>" tag. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

The exact Moodle version of a release can be found in [[Releases]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_RAW);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''NOTE:''' You might want extend language file for your block (lang/en/block_simplehtml.php) and add a value for "blockstring" defined in a code above.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_TEXT);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (isset($this->config)) {
if (empty($this->config->title)) {
$this->title = get_string('defaulttitle', 'block_simplehtml');
} else {
$this->title = $this->config->title;
}

if (empty($this->config->text)) {
$this->config->text = get_string('defaulttext', 'block_simplehtml');
}
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
<?php
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

=== Enabling Global Configuration ===
{{Moodle 2.4}}Since version 2.4, the following line must be added to the /blocks/simplehtml/block_simplehtml.php file in order to enable global configuration:
<code>
function has_config() {return true;}
</code>
This line tells Moodle that the block has a settings.php file.

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

'''NOTE:'''
If you don't return true in your cron function, the lastcron field in the blocks table will not be updated and as a result, your cron function will be called every time the cron runs!

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instances', array('blockname'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* Daniel Neis Araujo's [https://github.com/danielneis/moodle-block_newblock NEWBLOCK template].

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Blocks

2016-01-05T14:15:05Z

Scaroodle: Updated version.php according with MDL-48494 (Moodle 3.0).

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

Note: the latest information about how to develop a new module (not only a block) can be found in [[NEWMODULE Documentation]] and [https://github.com/moodlehq/moodle-mod_newmodule here], where a full module template code is available.

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned below, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for core blocks. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability is not required. The following is the capabilities array and how it should look for any new blocks.

<code php>
<?php
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with the capabilities we created and any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).

The capabilities added above need descriptions for pages that allow setting of capabilities. These should also be added to the language file.

<code php>
<?php
$string['pluginname'] = 'Simple HTML block';
$string['simplehtml'] = 'Simple HTML';
$string['simplehtml:addinstance'] = 'Add a new simple HTML block';
$string['simplehtml:myaddinstance'] = 'Add a new simple HTML block to the My Moodle page';
</code>

=== version.php ===

This file will hold version information for the plugin, along '''with other advanced parameters''' (not covered here - see [[version.php]] if you want '''more details''').

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
<?php
$plugin->component = 'block_simplehtml'; // Recommended since 2.0.2 (MDL-26035). Required since 3.0 (MDL-48494)
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the full [[Frankenstyle|frankenstyle]] component name in the form of ''plugintype_pluginname'' and the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also we don't include a closing "?>" tag. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

The exact Moodle version of a release can be found in [[Releases]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_RAW);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''NOTE:''' You might want extend language file for your block (lang/en/block_simplehtml.php) and add a value for "blockstring" defined in a code above.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_TEXT);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (isset($this->config)) {
if (empty($this->config->title)) {
$this->title = get_string('defaulttitle', 'block_simplehtml');
} else {
$this->title = $this->config->title;
}

if (empty($this->config->text)) {
$this->config->text = get_string('defaulttext', 'block_simplehtml');
}
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
<?php
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

=== Enabling Global Configuration ===
{{Moodle 2.4}}Since version 2.4, the following line must be added to the /blocks/simplehtml/block_simplehtml.php file in order to enable global configuration:
<code>
function has_config() {return true;}
</code>
This line tells Moodle that the block has a settings.php file.

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

'''NOTE:'''
If you don't return true in your cron function, the lastcron field in the blocks table will not be updated and as a result, your cron function will be called every time the cron runs!

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instances', array('blockname'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* Daniel Neis Araujo's [https://github.com/danielneis/moodle-block_newblock NEWBLOCK template].

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Time API

2015-04-23T06:02:30Z

Scaroodle: /* Time API's for current user */ Improved commenting style, according with https://docs.moodle.org/dev/Coding_style#Inline_comments

==Overview==

Internally Moodle always stores all times in unixtime format (number of seconds since epoch) which is independent of timezones.

The Time API is used to display proper date-time depending on user or site timezones.

==Functions==
Functions related to time api can be found in lib/moodlelib.php.
# Time API's for current user
#* '''make_timestamp''' - Given date-time, it produces a GMT timestamp for current user.
#* '''userdate''' - Gets formatted string that represents a date in user time
#* '''usertime''' - Given a GMT timestamp (seconds since epoch), offsets it by the timezone. eg 3pm in India is 3pm GMT - 5.5 * 3600 seconds
#* '''usergetdate''' - Given a timestamp in GMT, returns an array that represents the date-time in user time
#* '''usergetmidnight''' - Given a date, return the GMT timestamp of the most recent midnight for the current user.
#* '''usertimezone''' - Returns current user's timezone
#* '''get_user_timezone_offset''' - Returns user's timezone difference from GMT in hours
# System Time API
#* '''format_time''' - Format a date/time (seconds) as weeks, days, hours etc as needed
#* '''get_timezone_offset''' - Systems's timezone difference from GMT in seconds
#* '''dst_changes_for_year''' - Calculates the required DST change and returns a Timestamp Array
#* '''dst_offset_on''' - Calculates the Daylight Saving Offset for a given date/time (timestamp)
#* '''find_day_in_month''' - Calculates when the day appears in specific month
#* '''days_in_month''' - Calculate number of days in a given month
#* '''dayofweek''' - Calculate the position in the week of a specific calendar day

==Glossary==
===Timezone===
Moodle supports following timezone formats:
# UTC (specifically UTC−11 to UTC+11)
# Time offsets from UTC (int +-(0-13) or float +-(0.5-12.5))
# World timezones (Australia/Perth)

===Location===
Timezone depends on [[:en:Location]] of the user and can be forced upon by administrator.
===DST===
DST is abbreviation of '''Day light saving'''. Many countries, and sometimes just certain regions of countries, adopt daylight saving time (also known as "Summer Time") during part of the year. Moodle automatically calculates DST for current user, depending on user location.
==Examples==
===Time API's for current user===
Prints a formatted date in user time
<pre>
// Get current day, month and year for current user.
$date = usergetdate(time());
list($d, $m, $y) = array($date['mday'], $date['mon'], $date['year']);
// Print formatted date in user time.
echo userdate(make_timestamp($y, $m), "Current user time");
</pre>

===System Time API===
Find start month day
<pre>
$now = usergetdate(time());
echo find_day_in_month($now['mday'] - 6, $startweekday, $now['mon'], $now['year']);
</pre>

==See also==

* [[Core APIs]]

[[Category:API]]

Time API

2015-04-23T05:59:59Z

Scaroodle: /* Timezone */ Fixed typo.

==Overview==

Internally Moodle always stores all times in unixtime format (number of seconds since epoch) which is independent of timezones.

The Time API is used to display proper date-time depending on user or site timezones.

==Functions==
Functions related to time api can be found in lib/moodlelib.php.
# Time API's for current user
#* '''make_timestamp''' - Given date-time, it produces a GMT timestamp for current user.
#* '''userdate''' - Gets formatted string that represents a date in user time
#* '''usertime''' - Given a GMT timestamp (seconds since epoch), offsets it by the timezone. eg 3pm in India is 3pm GMT - 5.5 * 3600 seconds
#* '''usergetdate''' - Given a timestamp in GMT, returns an array that represents the date-time in user time
#* '''usergetmidnight''' - Given a date, return the GMT timestamp of the most recent midnight for the current user.
#* '''usertimezone''' - Returns current user's timezone
#* '''get_user_timezone_offset''' - Returns user's timezone difference from GMT in hours
# System Time API
#* '''format_time''' - Format a date/time (seconds) as weeks, days, hours etc as needed
#* '''get_timezone_offset''' - Systems's timezone difference from GMT in seconds
#* '''dst_changes_for_year''' - Calculates the required DST change and returns a Timestamp Array
#* '''dst_offset_on''' - Calculates the Daylight Saving Offset for a given date/time (timestamp)
#* '''find_day_in_month''' - Calculates when the day appears in specific month
#* '''days_in_month''' - Calculate number of days in a given month
#* '''dayofweek''' - Calculate the position in the week of a specific calendar day

==Glossary==
===Timezone===
Moodle supports following timezone formats:
# UTC (specifically UTC−11 to UTC+11)
# Time offsets from UTC (int +-(0-13) or float +-(0.5-12.5))
# World timezones (Australia/Perth)

===Location===
Timezone depends on [[:en:Location]] of the user and can be forced upon by administrator.
===DST===
DST is abbreviation of '''Day light saving'''. Many countries, and sometimes just certain regions of countries, adopt daylight saving time (also known as "Summer Time") during part of the year. Moodle automatically calculates DST for current user, depending on user location.
==Examples==
===Time API's for current user===
Prints a formatted date in user time
<pre>
//get current day, month and year for current user
$date = usergetdate(time());
list($d, $m, $y) = array($date['mday'], $date['mon'], $date['year']);
//Print formatted date in user time
echo userdate(make_timestamp($y, $m), "Current user time");
</pre>
===System Time API===
Find start month day
<pre>
$now = usergetdate(time());
echo find_day_in_month($now['mday'] - 6, $startweekday, $now['mon'], $now['year']);
</pre>

==See also==

* [[Core APIs]]

[[Category:API]]

Automated code review

2015-03-15T11:26:06Z

Scaroodle: Typo

Moodle issues submitted for review and inclusion into core are examined by our continuous integration (ci) system and checked against various automated tests. We use the automated checks to help improve the code quality in Moodle.

== What is CiBot? ==
CiBot is our automated code checker and it will run checks against any issues waiting for peer review, sent for integration or requested to be checked by the developer. It will report problems discovered in lines of your patch which you are changing.

== What checks is CiBot carrying out on each issue? ==
* Verify mergeability, number of commits and branch ages.
* Require testing instructions.
* Automated php syntax check using php -l and [https://github.com/moodlehq/moodle-local_ci/tree/master/php_lint these scripts]
* Automated [https://docs.moodle.org/dev/Coding_style coding style] checks using [https://moodle.org/plugins/view.php?plugin=local_codechecker local_codechecker].
* Automated [https://docs.moodle.org/dev/Coding_style#Documentation_and_comments PHPDoc] checks using [https://moodle.org/plugins/view.php?plugin=local_moodlecheck local_moodlecheck].
* Automated [https://docs.moodle.org/dev/Commit_cheat_sheet#Provide_clear_commit_messages commit message] checks using [https://github.com/moodlehq/moodle-local_ci/tree/master/verify_commit_messages these scripts].
* Automated [http://docs.moodle.org/dev/Upgrade_API upgrade savepoint] checks using [https://github.com/moodlehq/moodle-local_ci/tree/master/check_upgrade_savepoints these scripts].
* Automated [http://www.jshint.com jshint] javascript linting checks using the [https://github.com/moodle/moodle/blob/master/.jshintrc .jshintrc] configuration shipped with Moodle
* Automated [https://github.com/CSSLint/csslint csslint] CSS linting checks using the [https://github.com/moodle/moodle/blob/master/.csslintrc .csslintrc] configuration shipped with Moodle
* Automated third party library modification check using [https://github.com/moodlehq/moodle-local_ci/tree/master/thirdparty_check these scripts]

== Will an issue be automatically rejected if cibot checks fail? ==
No. Developers should strive to have cibot approve every patch submitted, but the integration team will take a pragmatic approach to things like:
* Occasions where cibot will detect issues present in existing code (see [[#Should coding style issues in existing code be fixed?|next item]])
* Variations from commit message style which make the commit message more understandable overall

== Should coding style issues in existing code be fixed? ==

In short, please only update lines relating to your own change.

There are some conventions that are not uniformly followed in the code base, many of these are conventions put in place after code was written. Our long term goal is for the entire codebase to follow the conventions, but in general, we don't want large-scale reformatting of existing code. See [[Coding_style#Policy_about_coding-style_only_fixes]].

=== Example situations ===
==== Spacing of if statements is incorrect on the line being changed ====
This can be corrected without affecting existing code, so should be fixed.

==== The line being changed contains an invalid variable name ====
If correcting this variable would affect other parts of the code not covered by the patch then it's not reasonable to fix it.

== Requesting CiBot checks an issue ==
At any time a developer can add the label 'cime' to an issue to request it runs it checks against it. The bot [https://github.com/moodlehq/moodle-local_ci/blob/master/tracker_automations/bulk_precheck_issues/criteria/developer_request/query.sh checks for issues with the cime label] every 20mins and runs the checks then remove the cime label. (Note that because it removes the label, it is normal to 'create' the label).

Any issue [https://github.com/moodlehq/moodle-local_ci/blob/master/tracker_automations/bulk_precheck_issues/criteria/awaiting_peer_review/query.sh submitted for peer review] or [https://github.com/moodlehq/moodle-local_ci/blob/master/tracker_automations/bulk_precheck_issues/criteria/awaiting_integration/query.sh integration review] will be checked automatically as long as it does not already have the 'ci' label.

== Are additional CiBot checks possible? ==
Yes. It is planned to add more checks - (see MDLSITE-3267) and developers are encouraged to suggest new checks in that issue. Note that some limitations exist:
* The checks should be consistent and completely reproducible
* The check should complete in minutes not hours (other solutions are in planning for longer term tests)

== The git commit summary limit is too small ==
When you overrun the length limit many git tools do not display commits well. See how [https://github.com/moodle/moodle/commits/ea6f5480818c31763f91a90a0cafb6a63ca18117 github truncates ea6f548081] - it ruins the message and makes it harder for you to communicate your change to other developers.

It is acknowledged that its often tricky to get a useful message in such a short space on the first line. However, the coding guidelines for git summary line length were established on the basis of [https://github.com/blog/926-shiny-new-commit-styles industry] [http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=aad7fb916a10f1065ad23de0c80a4a04bcba8437#n594 best] [http://stackoverflow.com/questions/2290016/git-commit-messages-50-72-formatting practice]. As the [[Coding_style#Git_commits]] mentions, do not be afraid to go into much more detail in your commit body.

Try <pre>git log --oneline --no-merges</pre> if you want to see how other developers have tried to adapt to this situation.

== Branches based off integration.git ==
The integration.git repository exists separately from moodle.git intentionally to indicate that its the place that '''history rewrites will happen'''. If a branch is based on outdated history which has been rewritten and is later attempted to merge it will result in a mess (repeated history, attempt to re-introduce previously reverted changes). It is for this reason that we strongly recommend against any branches being created based on the integration.git branches due its changing nature. This problem is emphasised because history rewrites will commonly happen at the end of a weekly cycle, immediately before releasing the changes to moodle.git.

There are some rare cases where basing a branch off integration.git might be sensible:
* Where the change would have non-trivial conflicts with integration.git changes (e.g. two commits changing the same function)
* Could not be branched from moodle.git with these conflicts resolved
If this case applies:
* CiBot will warn about the branch being based off integration.git
* The developer is expected to rebase once integration.git changes have been introduced to moodle.git to ensure that history-rewrites will not cause a merge mess

If these case do not apply, we expect that you '''do not''' produce your branches based on integration.git.

==Why are issues held up by trivial issues reported which don't affect the functionality of the change?==

Moodle is a large software project, it is common that 50 different developers will change the same file. Some may produce one fix and never be seen again, others will produce hundreds of fixes. The purpose of our coding conventions is to help all developers communicate with a consistent style so that we can look at all changes and understand their purpose with out getting distracted by changes in style.

While the issues reported might be trivial compared to benefit of the fix, over the long term, communicating your change well through coding and commit conventions might be far more important.

<blockquote>
" programs must be written for people to read, and only incidentally for machines to execute"
</blockquote>
― Hal Abelson, Structure and Interpretation of Computer Programs

==See also==

* [[Coding style]] and other links in the [[:Category:Coding guidelines|coding guidelines category]]

[[Category:Coding guidelines|Coding style]]

Git for developers

2014-06-01T08:55:08Z

Scaroodle: /* Cherry-picking a single commit */ Added a short description of a multiple cherry-picking command though the page suggests a different path.

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You may ask for a peer review of your code from another developer (preferred but optional)
* When you are confident of your code you should submit it for integration (Integration request, also sometimes known as a pull request)
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and the testing on Tuesday. On Wednesday, the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

If you'd like to be added to the developers group in the tracker (which allows you to assign issues to yourself), please send an email to michaeld@moodle.com with your tracker username and a link to an issue where you have contributed a patch.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/sh
git fetch upstream
for BRANCH in MOODLE_19_STABLE MOODLE_20_STABLE MOODLE_21_STABLE MOODLE_22_STABLE MOODLE_23_STABLE MOODLE_24_STABLE MOODLE_25_STABLE MOODLE_26_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-nasty-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push MDL-xxxxx-nasty-bug

Because we did not specify explicit remote repository, the 'origin' is used. Because we did not specify the branch to push, the Git will use the current branch and push it to the remote repository under the same name (by default, this is a subject of your configuration. See push.default config variable).

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the CONTHERE The command (1) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (2) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.

[[Category:Git]]

[[ja:開発者用Git]]

Events API

2013-12-29T09:27:20Z

Scaroodle: /* Triggering events */ Fixed a typo preventing the work of the hyperlink for the Verb list

{{Infobox Project
|name = Events 2
|state = Implementation in progress
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system.

Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why is a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement will be useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined if we want to use them for new logging and other advanced use cases. They need to contain a lot more information in a standardised way (such as most fields from current log table and log_actions table).
* Complex data types were allowed in old events which was causing major problems when serialising/storing/unserializing the data.
* The logging and events contain similar information and are tiggered at the same places, new events would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system will become an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It will be possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Current handlers do not get event name which makes this problematic.
* Current event handlers may trigger exceptions during site upgrade which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in handlers blocked dispatching of subsequent events. Instead problems in new observers would be only logged and execution would continue normally.
* Current execution of external handlers during DB transactions blocks other handlers. This would be eliminated by in-memory buffer for external events.
* It would good to have observer priority.
* Nested events are not dispatched sequentially, it would change the order of events received in lower priority handlers.

= Performance =
Some basic profiling has been conducted.

There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be imemented in parallel with the old one which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to trigger more events and log more information, which is going to impact on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin will define the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach will have several benefits.
; Events will be active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object will be able to provide callback functions for various purposes (such as capability checks).
; Automatic inclusion
: Event class definitions will be automatically included when needed, without having to maintain lists of known event types. New event definitions can be added without the need to upgrade, only purging of MUC cache is required after adding new observer.
; Maintainability
: It will be easy to add new events and migrate existing events. Code review will be simplified because there will be less duplication of code when triggering events and all event related information/code will be concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events will be combined with the definition of events in one place (file). It will be easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects common typos.

== Backwards compatibility and migration ==

Events:
* Moodle core and standard plugins will replace all calls to the events_trigger() function with new events classes.
* For events that already exist in Moodle 2.5 the additional legacy information should be added to the event data (in properties 'legacyeventname' and 'legacyeventdata'.
* The function events_trigger() will continue working as before, but it will be called automatically after a new event is processed using the 'legacyeventname' and 'legacyeventdata'.
* The legacy events handling code will be maintained separately and will continue being supported in Moodle 2.x. New legacy events will not be added.
* Existing legacy event handlers will be migrated to new event handlers accepting new event class instances.
* More subsystems may be migrated to events-handlers, ex.: gradebook history.

Logging:
* Function add_to_log() and all logging internals will continue working as before.
* Existing add_to_log() parameters will be migrated inside new events method get_legacy_log_data() and core_event_base::trigger() will call add_to_log() automatically (this will depend on $CFG->loglifetime setting for performance reasons).

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

The observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname - event class name or "*" indicating all events. All events must use namespace, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available events.php files. Previously handlers were installed only during installation and upgrade. There is no risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# New event data must not contain any PHP classes.
# There is separate context cache which may be used when deleting data or for observer performance improvements.
# No database access in new event dispatching code.
# There is no support for cron execution - this eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading - smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event descriptions are objects extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class name is a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Plugins define each event class in a separate file. File name and location must match the class name, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow our standard naming convention. The last word after underscore is automatically parsed as action, the rest of words is object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of php autoloading ===

All new OOP APIs in Moodle 2.6 are going to use class auto loading - see [[Automatic class loading]]. New events use PHP strictly defined namespaces which concentrate all events classes in classes/event/ subdirectory.

=== Why separate classes? ===
There were two alternatives proposed on how to define the event structure. The first is a separate class for each event (extending the base class), the other being each event is based on a generic event instance of the base class.
<pre>
Decision: Use separate class for each event.
</pre>
'''Each plugin creates its own event class for each event'''

Pros
* Maintainability - It is much easier to review, debug, integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatically lists events without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).

'''Each plugin defines events in a list based on a generic object'''

Pros
* Easier for some developers (this can be eliminated with developer documentation).
* Some developers think it gives more control of event structure in core (we can easily solve that with private access and validation in the base class).
Cons
* It is not flexible enough. PHP code gives developers more freedom.
* It would not be possible to implement any performance hacks in custom methods. All data would have to be calculated even if it is not used.
* It would be necessary to define access control callbacks in other code.
* It would be harder and slower to integrate legacy logging.
* It would be harder and slower to implement support for legacy events.
* Event observers could not use event class names as reliable identifiers.
* Event object and action could not be parsed from class name, it would have to be stored in event properties every time you trigger event.
* Requires upgrade/install to register an event in DB table with MUC cache. Events could not be triggered earlier.
* The localised descriptions and names would have to be stored as properties, it would not be possible to store them in any definition.
* The implementation of an events infrastructure would be significantly more complex and error prone.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delaying the computation of the data at the time it is really needed, if it ever is.

=== Properties ===

List of properties that the developer has to pass to the event upon creation, or automatically generated when possible and cost free. Some of those properties not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
|
| optional database table name where is/was the object stored. Never use a relationship table here.
|-
| objectid
| Object ID
|
| optional id of the object record from objecttable
|-
| '''''crud'''''
| Transaction type
| ''static mandatory''
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level'''''
| Level
| ''static mandatory''
| Level of educational value of the event. Statically declared in the event class method init(). (See below for more details)
|-
| contextid
| Context ID
| mandatory
|
|-
| contextlevel
| Context level
| automatic from context
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
|
| Is this action related to some user? This could be used for some personal timeline view.
|-
| other
| All other data
|
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
|
|}

* ''static'': It is the same for all event instances of this class.
* '''mandatory''': Is required in order to trigger the event.

==== Level property ====

The level property helps defining the educational value of the event. It is intentional that the list is limited to only 3 different constants, having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is affecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns localised description of one particular event.
|-
| can_view($user)
| Can the specified user view the event?
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards.
|-
| get_legacy_eventname()
| Information necessary for event BC.
|-
| get_legacy_eventdata()
| Information necessary for event BC.
|-
| get_legacy_logdata()
| Information necessary for logging BC.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc. The snapshot is meant to be a full database record, as it will be automatically fetched from get_record_snapshot() if not set previously and assuming the property ''objecttable'' is set. Please be aware that the snapshots are not stored in the event, and cannot be restored.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

=== Rejected properties and methods ===

{| class="nicetable"
|-
! Property
! Title
! Why
|-
| URL
| relevant page URL
| These URLs can be constructed on the fly from other data, external log plugins may use get_url() method.
|-
| version
| Event specification number
| The event specification should never change
|-
| type
| Type of event (action, error, ...)
| Event are not intended for error logging or debugging.
|-
| actor
| Whether current execution is cron, cli, user, ...
| Impossible to track down at a low level
|-
| severity
| Severity following [http://tools.ietf.org/html/rfc5424#section-6.2.1 logging standards]
| Our logging does not match this, as we will not (at present) log errors
|-
| coursecatname
| Category name
| Might be costly to retrieve for little gain
|-
| coursename
| Course name
| Might be costly to retrieve for little gain
|-
| cmname
| Course module name
| Might be costly to retrieve for little gain
|-
| categoryid
| Course category id
| Categories are a tree structure, we can not identify them by one integer. It would have to be a path.
|-
| cmid
| Course module id
| Can be derived from contextlevel and contextinstanceid
|-
| associatedobject
| Associated object
| Object associated to the main object. Ie: The user to whom a message is sent.
|-
| associatedobjectid
| Associated object ID
| Identifier of the associated object
|-
| realuserid
| Real User ID
| Will be tracked by log plugins only - user who "logged in as", stores the real user ID
|-
| origin
| Origin of the event
| Will be tracked by log plugins only - CLI, cron, Webservice, ... (optionally with IP address)
|}

{| class="nicetable"
|-
! Method
! Comment
! Why
|-
| get_all_affected_users()
| Returns all the users affected by this event
| It is expensive to fetch all users and it changes in time, so it would be unreliable too. For now we store only one user who is related to each event.
|-
| get_objecturl()
| Returns the URL to view the object
| There is usually only one URL where event changes may be observed. The URL may depend on current user capabilities too.
|-
| get_associatedobjecturl()
| Returns the URL to view the associated object
| No associated user property is present.
|-
| get_currenturl()
| Returns the current URL, uses $PAGE.
| This information may be added by logger, current page info is not part of events data.
|-
| get_useripaddress()
| Returns the User IP address
| Page access method is not part of events API, this should be implemented as logdata properties in loggers.
|}

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Structure of existing events ===

List of existing events called in 2.5, along with their future name and the decomposition of the new name into ''action'' and ''object''.

{| class="nicetable"
|-
! 2.5 name
! New name
! Subject
! Action
! Object
! <relationship>
! Object 2
! Comment
|-
| activity_completion_changed
| '''core_event_activity_completion_updated'''
| Someone
| changed
| completion
| of
| activity
|-
| assessable_content_uploaded
| '''mod_*_event_assessablecontent_uploaded'''
| Someone
| uploaded
| assessablecontent
|-
| assessable_files_done
| '''mod_*_event_assessablecontent_processed'''
| Someone
| processed
| assessable content
|
|
|
|-
| assessable_file_uploaded
|
| Someone
| uploaded
| assessable_file
|
|
| ''To be deprecated MDL-35197''
|-
| assessable_submitted
| '''mod_*_event_assessablecontent_submitted'''
| Someone
| submitted
| assessable content
|-
| blog_entry_added
| '''mod_blog_event_entry_created'''
| Someone
| added
| entry
|-
| blog_entry_deleted
| '''mod_blog_event_entry_deleted'''
| Someone
| deleted
| entry
|-
| blog_entry_edited
| '''mod_blog_event_entry_updated'''
| Someone
| updated
| entry
|-
| cohort_added
| '''core_event_cohort_created'''
| Someone
| created
| cohort
|-
| cohort_deleted
| '''core_event_cohort_deleted'''
| Someone
| deleted
| cohort
|-
| cohort_updated
| '''core_event_cohort_updated'''
| Someone
| updated
| cohort
|-
| cohort_member_added
| '''core_event_cohort_member_added'''
| Someone
| added
| member
| to
| cohort
|-
| cohort_member_removed
| '''core_event_cohort_member_deleted'''
| Someone
| deleted
| member
| from
| cohort
|-
| course_category_deleted
| '''core_event_coursecat_deleted'''
| Someone
| deleted
| coursecat
|-
| course_completed
| '''core_event_course_completed'''
| Someone
| completed
| course
|-
| course_content_removed
| '''core_event_course_purged'''
| Someone
| purged
| course
|-
| course_created
| '''core_event_course_created'''
| Someone
| created
| course
|-
| course_deleted
| '''core_event_course_deleted'''
| Someone
| deleted
| course
|-
| course_restored
| '''core_event_course_restored'''
| Someone
| restored
| course
|-
| course_updated
| '''core_event_course_updated'''
| Someone
| updated
| course
|-
| groups_group_created
| '''core_event_group_created'''
| Someone
| created
| group
|-
| groups_group_deleted
| '''core_event_group_deleted'''
| Someone
| deleted
| group
|-
| groups_grouping_created
| '''core_event_grouping_created'''
| Someone
| created
| grouping
|-
| groups_grouping_deleted
| '''core_event_grouping_deleted'''
| Someone
| deleted
| grouping
|-
| groups_groupings_deleted
|
| Someone
| deleted
| groupings
|
|
| ''To deprecate''
|-
| groups_groupings_groups_removed
|
| Someone
| removed
| groups
| from
| groupings
| ''To deprecate''
|-
| groups_grouping_updated
| '''core_event_grouping_updated'''
| Someone
| updated
| grouping
|-
| groups_groups_deleted
|
| Someone
| deleted
| groups
|
|
| ''To deprecate''
|-
| groups_group_updated
| '''core_event_group_updated'''
| Someone
| updated
| group
|-
| groups_member_added
| '''core_event_group_member_added'''
| Someone
| added
| member
| to
| group
|-
| groups_member_removed
| '''core_event_group_member_deleted'''
| Someone
| deleted
| member
| from
| group
|-
| groups_members_removed
|
| Someone
| removed
| members
| from
| group
| ''To deprecate''
|-
| lti_unknown_service_api_call
| '''mod_lti_event_unknownservice_called'''
| Someone
| called
| unknown service
|-
| mod_created
| '''core_event_module_created'''
| Someone
| created
| module
|-
| mod_deleted
| '''core_event_module_deleted'''
| Someone
| deleted
| module
|-
| portfolio_send
|
|
|
|
|
|
| ''This is a hack...''
|-
| role_assigned
| '''core_event_user_role_added'''
| Someone
| added
| role
| to
| user
| ''Or ..._role_assigned''
|-
| role_unassigned
| '''core_event_user_role_removed'''
| Someone
| removed
| role
| from
| user
| ''Or ..._role_unassigned''
|-
| quiz_attempt_started
| '''mod_quiz_event_attempt_started'''
| Someone
| started
| attempt
| of
| quiz
|-
| test_cron
|-
| test_instant
|-
| user_created
| '''core_event_user_created'''
| Someone
| created
| user
|-
| user_deleted
| '''core_event_user_deleted'''
| Someone
| deleted
| user
|-
| user_enrolled
| '''core_event_user_enrolment_created'''
| Someone
| added
| enrolment
| of
| user
|-
| user_enrol_modified
| '''core_event_user_enrolment_updated'''
| Someone
| updated
| enrolment
| of
| user
|-
| user_unenrolled
| '''core_event_user_enrolment_deleted'''
| Someone
| removed
| enrolment
| of
| user
|-
| user_logout
| '''core_event_loggedout'''
| Someone
| loggedout
|-
| user_updated
| '''core_event_user_updated'''
| Someone
| updated
| user
|-
| workshop_viewed
| '''mod_workshop_event_viewed'''
| Someone
| viewed
| workshop
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs should be added to this list if required.
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|attempted
|
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|called
|When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
| Used to represent "something new has been created".
|Moodle
|-
|deleted
| Used to indicate the object in context was deleted.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|previewed
|Something has been previewed.
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|registered
|Indicates the actor registered for a learning activity
|Tincan
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|restored
| When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|reset
| Sets one or more properties back to the default value.
|Moodle
|-
|revealed
|Example: Identities revealed after blind marking.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values.
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not use create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Development stages =

== Stage 1 ==

* Finish class loader spec and implement basic Frankenstyle class loader.
* Describe new observer definition - just few new flags in current db/events.php
* Describe new event dispatcher.
* Describe core_event_base class.
* Current (= legacy) events triggering:
** Re-factor current event handling code to new self-contained class - do not change functionality, keep events_trigger().
** Create new event handler management class that deals with installation and upgrades of both legacy and new handlers.
* New events:
** Create new core_event_base class.
** Create new self-contained event dispatcher class with '*' handler support.
** In function core_event_base::trigger() check if the event has property 'legacyeventname' execute events_trigger($this->legacyeventname, $this->legacyeventdata) after triggering new event.
** Write unit tests for all new events code.
* No changes to be made to the current logging system yet.

After completing this stage everything should continue to work as it did before and we can start parallel work on further stages.

== Stage 2 (requires completion of Stage 1) ==

* Create event classes and replace existing calls to events_trigger() and with new event classes containing legacy information properties.
* Add more events throughout the standard Moodle package in places where we have add_to_log(). Implement some_event::get_legacy_log_data() which returns original parameters of add_to_log() and remove it. Old add_to_log() function is called in core_event_base::trigger() automatically with original parameters.
* Add even more new events all over the place.

The difficult part is defining the new event classes properly because we must not change them after the 2.6 release.

== Stage 3 (requires partial completion of Stage 2) ==

* Migrate current legacy event handlers to new handlers with one event class instance parameter, ex.: enrol plugins.

== Stage 4 (requires partial completion of Stage 2) ==

* Implement an event logging handler.
* Implement logging storage plugins.
* Define logging apis.
* Create new reports.
* Switch to new logging everywhere after Stage 2 has been completed and new reports are usable.

See [[Logging 2]]

== Stage 5 ==

* Decide how much backwards compatibility we want for old log tables. Most probably they will get only legacy log data.
* Implement some BC solution for old code that reads log tables directly.

See [[Logging 2]]

== Stage 6 (requires completion of Stage 4 and 5) ==

Moodle 2.8dev? This is the ultimate end of old logging via the ''log'' table.

* Deprecate the add_to_log() function with a debug message and do nothing inside.
* Remove all legacy logging from event classes.

See [[Logging 2]]

User:Matteo Scaramuccia

2013-03-20T13:45:08Z

Scaroodle: Created page with "OSS supporter. ==See also== * [https://moodle.org/user/view.php?id=1075386&course=1 My moodle.org profile]"

OSS supporter.

==See also==

* [https://moodle.org/user/view.php?id=1075386&course=1 My moodle.org profile]

jQuery

2013-03-20T13:17:47Z

Scaroodle: Fixed trivial typo. BTW, great job Petr!

{{Moodle 2.5}}

'''WORK IN PROGRESS see MDL-15727'''

[[YUI]] is the recommended library for development of Moodle plugins or customisations. However due to significant demand it will be possible to use also jQuery in Moodle add-ons.

==Examples==

===Basic jQuery in add-on theme===

# create /theme/sometheme/lib.php file if it does not exist yet
# add new function theme_sometheme_page_init to the lib.php file (replace 'sometheme' with real name of your theme)
# use jQuery JavaScript in theme layout files

<code php>
<?php
// file: /theme/sometheme/lib.php
function theme_sometheme_page_init(moodle_page $page) {
$page->requires->jquery();
}
</code>

<code html4strict>
// near the end of file: /theme/sometheme/layout/general.php
<script>
$('.headermain').mouseover(function() {
alert('grrr');
});
</script>
</code>

===jQuery UI in add-on activity module===
# optionally add more jQuery plugins (not recommended because the same plugins in different add-ons may collide)
# add necessary $PAGE->requires
# use jQuery

<code php>

<?php
require('../../config.php');

// ... normal PAGE and access control

$PAGE->requires->jquery();
$PAGE->requires->jquery_plugin('ui');
$PAGE->requires->jquery_plugin('ui-css');

echo $OUTPUT->header();
?>
<button>A button element</button>

<div id="dialog" title="Basic dialog">
<p>This is the default dialog which is useful for displaying information. The dialog window can be moved, resized and closed with the 'x' icon.</p>
</div>
<script>
$(function() {
$( "#dialog" ).dialog();
});
</script>
<?php
echo $OUTPUT->footer();
</code>

===jQuery UI in add-on block===
# add necessary requires in get_required_javascript() method in your block, do not forget to call it in parent too
# use jQuery in blok html output

<code php>

class block_html extends block_base {

function get_required_javascript() {
parent::get_required_javascript();

$this->page->requires->jquery();
$this->page->requires->jquery_plugin('ui');
$this->page->requires->jquery_plugin('ui-css');
}

function get_content() {

// ....

$this->content->text .= '
<div id="progressbar"></div>
<script>
$(function() {
$( "#progressbar" ).progressbar({
value: 37
});
});
</script>';

// ....
}
</code>

===Override base jQuery UI theme===
# download new jQuery UI theme and extract it into theme/sometheme/jquery/custom-1.0
# define new jQuery theme ui css plugin in theme/sometheme/jquery/plugins.php
# overrider core 'ui-css' with 'yourtheme-ui-css'

<code php>
<?php
// file: theme/sometheme/jquery/plugins.php
$plugins = array(
'some-ui-css' => array('files' => array('custom-1.0/jquery-ui-1.10.2.custom.min.css')),
);
</code>

<code php>
<?php
// file: /theme/sometheme/lib.php
function theme_sometheme_page_init(moodle_page $page) {
// There is no need to $page->requires->jquery() if the theme does not use jQuery.
$page->requires->jquery_plugin('sometheme-ui-css', 'theme_sometheme');
$page->requires->jquery_override_plugin('ui-css', 'sometheme-ui-css');
}
</code>

===Backwards compatibility for scripts written for older jQuery scripts===

See [https://github.com/jquery/jquery-migrate/ jQuery Migrate plugin]

<code php>
$PAGE->requires->jquery_plugin('migrate');
</code>

===mymobile theme===

See mymobile theme for more information including custom jQuery plugins, integration with jQuery Mobile.

==More information==

===jQuery plugin collisions===

The loading order of plugins is defined by order of $PAGE->requires. If there are plugins with the same name the first $PAGE->require wins.

It is recommended to use plugin overrides only in themes because multiple overrides of the same plugin result in undefined behaviour. In general themes should have more freedom to add extra jQuery plugins, other Moodle plugins should ideally use only basic jQuery or jQuery UI.

===jQuery plugin modifications===

Files in jQuery plugins MUST NOT be changed, always create a new file with different name and update CSS and plugins.php if necessary and delete the old file.

===jQuery versions===

Only minor jQuery version updates can be done in STABLE branches. Add-on developers must revalidate compatibility after every major upgrade. Use official 'migrate' plugin if necessary, see example above.

==Frequently asked questions==

; Can I serve jQuery from CDN? : No, because CDNs do not include all plugins and some do not include https support. Use proxy caching such as Cloudflare instead.

; I edited some file but the change is ignored, why? : See above, files MUST NOT be updated in jQuery plugins, always create new files or directories. Moodle cache purging does not have any effect on jQuery plugins.

; Can we remove YUI now? : No! YUI is the only recommended JS library in Moodle add-ons and core.

; Can I use different jQuery version? : No. (Theoretically you might try jQuery plugin override to include some later minor revision.)

; Could we have jQuery plugin dependencies? : No, order your $PAGE->requires manually.

; Are there any performance costs when using jQuery? : Yes. Please consider using SimpleYUI for simple DOM manipulations or standard YUI widgets.

; Can I use YUI loader to include jQuery? : No. Moodle jQuery support is not compatible with sandboxing.

; Moodle complains when I disable slasharguments setting, why? : Please fix your server to be compatible with slasharguments, even IIS can support it now!

==See also==
* [http://jquery.com jQuery]
* [http://jqueryui.com jQuery User Interface]