MoodleDocs - User contributions [en]

Plugins directory API

2023-07-20T17:04:31Z

Mina: /* Example cURL client fetching the list of maintained plugins */ Fix code

{{Plugins development}}

The Plugins directory at http://moodle.org/plugins exposes some of its features via web services layer, allowing the community to develop custom tools and integrations with other services such as GitHub Actions or Travis CI.

== Access token ==

To use the web service described below, the caller (client) authenticates itself with an access token. In almost all cases, developers use their own personal token and let the scripts (clients) work on behalf of them.

The easiest way to obtain the access token (and some other useful information) is to visit ''Plugins > API access'' page at moodle.org through the side Navigation block.

The token can be alternatively obtained via the ''Preferences > Security keys'' or programatically via login/token.php script at moodle.org (however, tokens obtain that way have very short expiration in contrast with the ones generated at the dedicated page).

== Plugins maintenance service ==

The Plugins maintenance service (<tt>plugins_maintenance</tt>) provides functions for the plugins maintainers. The service is declared as:

<syntaxhighlight lang="php">
'Plugins maintenance' => [
'functions' => [
'local_plugins_get_maintained_plugins',
'local_plugins_add_version',
],
'shortname' => 'plugins_maintenance',
'requiredcapability' => 'local/plugins:editownplugins',
'enabled' => true,
'restrictedusers' => 0,
'downloadfiles' => true,
'uploadfiles' => true,
],
</syntaxhighlight>

=== Getting the list of maintained plugins ===

The first external function <tt>local_plugins_get_maintained_plugins</tt> allows to read the list of all plugins and their recent versions the caller is maintainer of. It does not expect any parameters and its return structure is described as follows:

<syntaxhighlight lang="php">
return new external_multiple_structure(
new external_single_structure([
'id' => new external_value(PARAM_INT, 'Internal plugin identifier'),
'name' => new external_value(PARAM_TEXT, 'Name of the plugin'),
'shortdescription' => new external_value(PARAM_TEXT, 'Short description'),
'description' => new external_value(PARAM_RAW, 'Description'),
'descriptionformat' => new external_format_value('description'),
'frankenstyle' => new external_value(PARAM_PLUGIN, 'Full component frankenstyle name'),
'type' => new external_value(PARAM_ALPHANUMEXT, 'Plugin type'),
'websiteurl' => new external_value(PARAM_URL, 'Website URL'),
'sourcecontrolurl' => new external_value(PARAM_URL, 'Source control URL'),
'bugtrackerurl' => new external_value(PARAM_URL, 'Bug tracker URL'),
'discussionurl' => new external_value(PARAM_URL, 'Discussion URL'),
'timecreated' => new external_value(PARAM_INT, 'Timestamp of plugin submission'),
'approved' => new external_value(PARAM_INT, 'Approval status'),
'visible' => new external_value(PARAM_BOOL, 'Visibility status'),
'aggdownloads' => new external_value(PARAM_INT, 'Stats aggregataion - downloads'),
'aggfavs' => new external_value(PARAM_INT, 'Stats aggregataion - favourites'),
'aggsites' => new external_value(PARAM_INT, 'Stats aggregataion - sites'),
'statusamos' => new external_value(PARAM_INT, 'AMOS registration status'),
'viewurl' => new external_value(PARAM_URL, 'View URL'),
'currentversions' => new external_multiple_structure(
new external_single_structure([
'id' => new external_value(PARAM_INT, 'Internal version identifier'),
'version' => new external_value(PARAM_INT, 'Version number'),
'releasename' => new external_value(PARAM_TEXT, 'Release name'),
'releasenotes' => new external_value(PARAM_RAW, 'Release notes'),
'releasenotesformat' => new external_format_value('releasenotes'),
'maturity' => new external_value(PARAM_INT, 'Maturity code'),
'changelogurl' => new external_value(PARAM_URL, 'Change log URL'),
'altdownloadurl' => new external_value(PARAM_URL, 'Alternative download URL'),
'md5sum' => new external_value(PARAM_TEXT, 'MD5 hash of the ZIP content'),
'vcssystem' => new external_value(PARAM_ALPHA, 'Version control system'),
'vcssystemother' => new external_value(PARAM_TEXT, 'Name of the other version control system'),
'vcsrepositoryurl' => new external_value(PARAM_URL, 'Version control system URL'),
'vcsbranch' => new external_value(PARAM_TEXT, 'Name of the branch with this version'),
'vcstag' => new external_value(PARAM_TEXT, 'Name of the tag with this version'),
'timecreated' => new external_value(PARAM_INT, 'Timestamp of version release'),
'approved' => new external_value(PARAM_INT, 'Approval status'),
'visible' => new external_value(PARAM_BOOL, 'Visibility status'),
'supportedmoodle' => new external_value(PARAM_TEXT, 'Comma separated list of support Moodle versions'),
'downloadurl' => new external_value(PARAM_URL, 'Download URL'),
'viewurl' => new external_value(PARAM_URL, 'View URL'),
'smurfresult' => new external_value(PARAM_TEXT, 'Code prechecks results summary'),
])
),
])
);
</syntaxhighlight>

==== Example cURL client fetching the list of maintained plugins ====

<syntaxhighlight lang="bash">
#!/bin/bash

# Replace this with your own service access token.
TOKEN="d41d8cd98f00b204e9800998ecf8427e"

CURL="curl -s"
ENDPOINT=https://moodle.org/webservice/rest/server.php
FUNCTION=local_plugins_get_maintained_plugins

${CURL} ${ENDPOINT} --data-urlencode "wstoken=${TOKEN}" --data-urlencode "wsfunction=${FUNCTION}" \
--data-urlencode "moodlewsrestformat=json" | jq
</syntaxhighlight>

=== Releasing a new version ===

The second function <tt>local_plugins_add_version</tt> allows to release a new version to the plugin. The input parameters are described as:

<syntaxhighlight lang="php">
return new external_function_parameters([
// The pluginid or frankenstyle must be provided (in this order of precedence).
'pluginid' => new external_value(PARAM_INT, 'Internal identifier of the plugin', VALUE_DEFAULT, null),
'frankenstyle' => new external_value(PARAM_PLUGIN, 'Full component name of the plugin', VALUE_DEFAULT, null),
// ZIP can be specified by draft area itemid (with single file in it), content or URL (in this order of precedence).
'zipdrafitemtid' => new external_value(PARAM_INT, 'Itemid of user draft area with uploaded ZIP', VALUE_DEFAULT, null),
'zipcontentsbase64' => new external_value(PARAM_RAW, 'ZIP file contents encoded with MIME base64', VALUE_DEFAULT, null),
'zipurl' => new external_value(PARAM_URL, 'ZIP file URL', VALUE_DEFAULT, null),
// Following params may be auto-detected from the ZIP content.
'version' => new external_value(PARAM_INT, 'Version number', VALUE_DEFAULT, null),
'releasename' => new external_value(PARAM_TEXT, 'Release name', VALUE_DEFAULT, null),
'releasenotes' => new external_value(PARAM_RAW, 'Release notes', VALUE_DEFAULT, null),
'releasenotesformat' => new external_format_value('releasenotes', VALUE_DEFAULT, FORMAT_MOODLE),
'maturity' => new external_value(PARAM_INT, 'Maturity code', VALUE_DEFAULT, null),
'supportedmoodle' => new external_value(PARAM_TEXT, 'Comma separated list of supported Moodle versions',
VALUE_DEFAULT, null),
// Other optional properties.
'changelogurl' => new external_value(PARAM_URL, 'Change log URL', VALUE_DEFAULT, null),
'altdownloadurl' => new external_value(PARAM_URL, 'Alternative download URL', VALUE_DEFAULT, null),
'vcssystem' => new external_value(PARAM_ALPHA, 'Version control system', VALUE_DEFAULT, null),
'vcssystemother' => new external_value(PARAM_TEXT, 'Name of the other version control system', VALUE_DEFAULT, null),
'vcsrepositoryurl' => new external_value(PARAM_URL, 'Version control system URL', VALUE_DEFAULT, null),
'vcsbranch' => new external_value(PARAM_TEXT, 'Name of the branch with this version', VALUE_DEFAULT, null),
'vcstag' => new external_value(PARAM_TEXT, 'Name of the tag with this version', VALUE_DEFAULT, null),
]);
</syntaxhighlight>

The API has been designed so that:

* The actual ZIP can be taken from pre-uploaded file (standard way of using webservice/upload.php), or submitting the file contents directly, or providing an URL the ZIP should be fetched from.
* As many as possible parameters (such as list of supported Moodle versions, release name, release notes etc) default to the values specified in the ZIP itself.
* So it should be enough to specify just the plugin (either by numerical ID number of frankenstyle) and the ZIP with the new version. All other values are optional and can be used to override the auto-detected ones.

When successful, the external function's response is described as:

<syntaxhighlight lang="php">
return new external_single_structure([
'id' => new external_value(PARAM_INT, 'Internal identifier of the newly created version'),
'md5sum' => new external_value(PARAM_TEXT, 'MD5 hash of the ZIP content'),
'timecreated' => new external_value(PARAM_INT, 'Timestamp of version release'),
'downloadurl' => new external_value(PARAM_URL, 'Download URL'),
'viewurl' => new external_value(PARAM_URL, 'View URL'),
'warnings' => new external_multiple_structure(
new external_value(PARAM_RAW, 'Validation warnings')
),
]);
</syntaxhighlight>

==== Example CLI script to release a new version of a plugin ====

<syntaxhighlight lang="bash">
#!/bin/bash

# Replace this with your own service access token.
TOKEN="d41d8cd98f00b204e9800998ecf8427e"

# Set the full component name of the plugin.
PLUGIN=mod_subcourse
# Path to the ZIP fle with the new version.
ZIP=version.zip

CURL="curl -s"
HOST="https://moodle.org/"
ENDPOINT_REST="${HOST}/webservice/rest/server.php"
ENDPOINT_UPLOAD="${HOST}/webservice/upload.php"

ITEMID=$(${CURL} -F data=@${ZIP} "${ENDPOINT_UPLOAD}?token=${TOKEN}" | jq --raw-output '.[0].itemid')

${CURL} ${ENDPOINT_REST} --data-urlencode "wstoken=${TOKEN}" --data-urlencode "wsfunction=${FUNCTION}" --data-urlencode "moodlewsrestformat=json" \
--data-urlencode "frankenstyle=${PLUGIN}" --data-urlencode "zipdrafitemtid=${ITEMID}" | jq
</syntaxhighlight>

==== GitHub Actions ====

A new workflow can be configured at GitHub Actions to automatically release a new version in the Plugins directory once a tag is pushed to the repository. Please see https://github.com/moodlehq/moodle-plugin-release for details.

Setting up development environment

2022-04-21T16:20:50Z

Mina: /* IDE */

This is a quick guide which contains all the tools you'll need to configure your development environment:

== Git ==
* [[Git_for_developers#Installing_Git_on_your_computer|Installation]]
* [[Git_for_developers#Setting-up the public repository|Setting-up GitHub]]

== Apache + PHP ==
* Depending on your computer's OS:
** [https://docs.moodle.org/en/Installing_Moodle_on_Debian_based_distributions#Step_1:_Install_required_packages Debian]
** [https://docs.moodle.org/en/Installation_on_OS_X OS X]
** [https://docs.moodle.org/en/Windows_installation Windows]: [https://docs.moodle.org/en/Installing_Apache_on_Windows Apache] + [https://docs.moodle.org/en/Installing_PHP_on_Windows PHP]
* [https://docs.moodle.org/en/PHP#PHP_Extensions_and_libraries Extensions and libraries]
* Enable SSL for Apache ([https://docs.moodle.org/en/Transitioning_to_HTTPS Transitioning to HTTPS])

More information: [https://docs.moodle.org/en/Category:Installation Category:Installation]

== Database ==
* Server:
** [https://docs.moodle.org/en/PostgreSQL PostgreSQL] (recommended)
** [https://docs.moodle.org/en/MariaDB MariaDB] (recommended)
** [https://docs.moodle.org/en/MySQL MySQL]
** [https://docs.moodle.org/en/MSSQL MSSQL]
** [https://docs.moodle.org/en/Oracle Oracle] (not recommended)
* Client:
** [https://www.adminer.org/ Adminer]

== Moodle ==

=== Manual installation ===
* [https://docs.moodle.org/en/Installation_quick_guide Quick guide]

=== Moodle Development Kit (MDK) ===
Only for Linux and MacOS (not available for Windows)
* [https://github.com/FMCorz/mdk#user-content-for-development Setup]
** Sample to create some instances (both based on master, first using PostgreSQL and second MySQL:
<syntaxhighlight lang="php">
mdk create --install --engine pgsql --run mindev users makecourse
mdk create --install --engine mysqli --run mindev users makecourse -n stable_master-mysql
</syntaxhighlight>
* [[Running_acceptance_test#2._Set_up_Selenium | Behat]]
** JRE
** GoogleChrome driver (Firefox stopped working)

=== Docker ===
* https://github.com/moodlehq/moodle-docker

== IDE ==
* [[Setting_up_Sublime2 | Sublime]]
* [[Setting_up_PhpStorm | PhpStorm]]
* [[Setting_up_Eclipse | Eclipse]]
* [[Setting_up_Netbeans | Netbeans]]
* [[Setting up ViM | ViM]]

== COMMAND LINE ==
To view logs in real time on linux based machines you can use at the command line : # tail - f

Example: # tail -f /var/log/apache2/error.log

By viewing logs in real time you will find it easier to correlate actions and errors.

== Other tools ==
* [[Grunt#Install_grunt | Grunt]]
* [https://ngrok.com/download Ngrok], for getting your dev/private site publicly available (for sharing, for testing various integrations requiring public site, SSL or no...)
** Use [https://ngrok.com/docs#authtoken authtoken] for better experience
** [https://gist.github.com/andrewnicols/a338c43feca0a87a60248b8097de2ef5 MDK integration]

[[Category:Developer tools|Development environment]]

Setting up PhpStorm

2022-04-16T15:54:32Z

Mina: /* Code formatting */ Update settings

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===

Do not install Java manually, download a PhpStorm package with bundled java instead.

==General settings==

* Uncheck "Missing @throws tag(s)" setting in "Preferences / Editor / Inspections / PHP / PHPDoc"
* Check "Strip trailing whitespace on Modified Lines" in "Preferences / Editor / General"
* Check "Show line numbers" in "Preferences / Editor / Appearance"
* Add Moodle database prefix by create file .phpstorm.meta.php in the project root directory, put the code below to enable PhpStorm recognized {table_name} as Database table:
<syntaxhighlight lang="php">
<?php

namespace PHPSTORM_META {
override(
// Virtual function to indicate that all SQL
// injections will have the following replacement rules.
sql_injection_subst(),
map([
'{' => "mdl_", // all `{` in injected SQL strings will be replaced with a prefix
'}' => '', // all `}` will be replaced with an empty string
]));
}
</syntaxhighlight>

==Bug tracker integration==

* Add tracker linking in "Preferences / Version control / Issue Navigation"
* Set Issue ID to "MDL-\d+|CONTRIB-\d+|MOBILE-\d+|MDLSITE-d+|MDLQA-\d+|UX-\d+|MDLNET-\d+|WPQA-\d+" and Issue link to "https://tracker.moodle.org/browse/$0" or just click on 'add Jira pattern' and paste "https://tracker.moodle.org"

==Code formatting==

* Setup coding style to use all rules from [[Coding style]] in "Preferences / Code Style / PHP" (or simply import from https://github.com/enovation/moodle-utils/blob/master/phpstorm-config/Moodle.xml) - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste.
* Set line separator to "Unix and OS X (\n)" in "Preferences / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Code Style / General".

==Tips & Tricks==

* Use <syntaxhighlight lang="php">/** @var admin_root $ADMIN */</syntaxhighlight> to autofill $ADMIN->...
* Remove SQL syntax inspection errors for Moodle tables surrounded by curly brackets (like: <syntaxhighlight lang="php">SELECT * FROM {user}</syntaxhighlight>) by adding <syntaxhighlight lang="php">\{(\w+)\}</syntaxhighlight> to Tools > Databases > user parameters
(more info: https://blog.jetbrains.com/phpstorm/2014/11/database-language-injection-configuration/ , and a "feature request" to improve it: https://youtrack.jetbrains.com/issue/WI-4123 )
* You can deactivate warnings for specific exceptions (in particular the coding_exception, which is unlikely to be catched in your code) by going to Settings > PHP and add them to 'Unchecked Exceptions' under the 'Analysis' tab

==Moodle code checker==
Follow the instructions in the [https://github.com/moodlehq/moodle-local_codechecker/blob/master/README.md#ide-integration README]

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

==Javascript Development==
You can work on Javascript development by add Grunt configuration:
# Install Watchman - https://facebook.github.io/watchman/docs/install.html
# From the main Moodle directory open terminal and run:
<syntaxhighlight lang="shell">
npm install -g grunt-cli
npm install
</syntaxhighlight>
# Open "Edit configuration"
# Add new Grunt Task
## Verify that the node version is set with proper version for the current Moodle version
## In Tasks select watch
# Save the Grunt task
# Verify that in config.php the setting is not comment
<syntaxhighlight lang="php">
$CFG->cachejs = false;
</syntaxhighlight>
# Click on run icon
# happy Javascript development

==Debugging with Xdebug with docker containers==

This is very helpful when developing locally and you need to go step by step on the execution path of something of your interest.

If you're using [https://github.com/moodlehq/moodle-docker moodle-docker], please refer to its section about [https://github.com/moodlehq/moodle-docker#using-xdebug-for-live-debugging live debugging] before taking this section. If you are using a custom docker container, the web server container should be based on Debian-like to have the following instructions compatible.

These are the steps for configuring Xdebug to live debugging your code:

# Be sure containers are stopped.
# If you're using Docker on Mac or Windows, you can omit this step. So, only if you're using Docker on linux: Create a file named `add-host.docker.internal-to-etc-hosts` with execution rights on the Moodle root:
<syntaxhighlight lang="php">
#!/bin/bash
apt update
apt install -y iproute2
apt clean
apt auto-clean
HOST_DOMAIN="host.docker.internal"
ping -q -c1 $HOST_DOMAIN > /dev/null 2>&1
if [ $? -ne 0 ]; then
HOST_IP=$(ip route | awk 'NR==1 {print $3}')
echo -e "$HOST_IP\t$HOST_DOMAIN" >> /etc/hosts
fi
</syntaxhighlight>
# Edit the <syntaxhighlight lang="php">base.yml</syntaxhighlight> from the moodle-docker root (or equivalent from your custom docker container) to append these lines into the <syntaxhighlight lang="php">webserver: environment:</syntaxhighlight> section:
<syntaxhighlight lang="php">
XDEBUG_CONFIG:
idekey=phpstorm
remote_enable=1
remote_mode=req
remote_port=9000
remote_host=host.docker.internal
remote_connect_back=0
PHP_IDE_CONFIG:
serverName=moodle-local
</syntaxhighlight>
# The result for the <syntaxhighlight lang="php">webserver</syntaxhighlight> service should be like this (this example is from moodle-docker):
<syntaxhighlight lang="php">
webserver:
image: "moodlehq/moodle-php-apache:${MOODLE_DOCKER_PHP_VERSION}"
depends_on:
- db
volumes:
- "${MOODLE_DOCKER_WWWROOT}:/var/www/html"
- "${ASSETDIR}/web/apache2_faildumps.conf:/etc/apache2/conf-enabled/apache2_faildumps.conf"
environment:
MOODLE_DOCKER_DBTYPE: pgsql
MOODLE_DOCKER_DBNAME: moodle
MOODLE_DOCKER_DBUSER: moodle
MOODLE_DOCKER_DBPASS: "m@0dl3ing"
MOODLE_DOCKER_BROWSER: firefox
MOODLE_DOCKER_WEB_HOST: "${MOODLE_DOCKER_WEB_HOST}"
XDEBUG_CONFIG:
idekey=phpstorm
remote_enable=1
remote_mode=req
remote_port=9000
remote_host=host.docker.internal
remote_connect_back=0
PHP_IDE_CONFIG:
serverName=moodle-local
</syntaxhighlight>
# Start the moodle-docker containers, or your custom ones.
# Only if you're using Docker on linux: From a PhpStorm terminal, run: <syntaxhighlight lang="php">docker exec -it moodledocker_webserver_1 ./add-host.docker.internal-to-etc-hosts</syntaxhighlight>. You have to see how packages are installed.
# In any type of host (Mac, Windows or linux): Check that <syntaxhighlight lang="php">/etc/hosts</syntaxhighlight> has a line with <syntaxhighlight lang="php">host.docker.internal</syntaxhighlight>. You can do that with the command <syntaxhighlight lang="php">docker exec -it moodledocker_webserver_1 cat /etc/hosts</syntaxhighlight> (if you have a custom container name, use the name for the webserver container). The result should be something like this:
<syntaxhighlight lang="php">
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.20.0.6 17dff32616ac
172.20.0.1 host.docker.internal
</syntaxhighlight>
# Go to your PhpStorm and go to <syntaxhighlight lang="php">Run -> Edit configurations</syntaxhighlight> and select new <syntaxhighlight lang="php">PHP Remove Debug</syntaxhighlight>
# Name: "xdebug localhost" (or what you want to)
# Configuration: check "Filter debug connection by IDE key"
# IDE key(session id): "phpstorm"
# Define a new server:
# Name: must be "moodle-local"
# Host: localhost
# Port: must be the port you're using for the web server.
# Debugger: use the default (Xdebug)
# Check "Use path mappings (...)"
# Set for your "Project files" Moodle root the "Absolute path on the server" as "/var/www/html"
# Apply and OK on this screen. This screen will be closed.
# Apply and OK on the next screen. Settings screen will be closed.
# Now, test that live debugging works. To do so, please:
# Put a breakpoint on /index.php file.
# Press telephone icon with a red symbol with title "Start listening for PHP Debug Connections": telephone should appear with some waves now.
# Open your browser and open your localhost Moodle site.
# Happy debugging ;-)

Final note: Every time you start the webserver container, ONLY if you're using a linux host, you have to run the script for adding the host.docker.internal.
Final note 2: This method also works if your docker containers are in a different host from localhost: you just need to specify the proper server name and port.
Final note 3: This configuration also allows you to debug CLI scripts.

==Useful plugins==

# Php Inspections (EA Extended) - https://plugins.jetbrains.com/plugin/7622-php-inspections-ea-extended-/
# SonarLint - https://plugins.jetbrains.com/plugin/7973-sonarlint/
# Diff / Patch File Support - https://plugins.jetbrains.com/plugin/11957-diff--patch-file-support/
# Handlebars/Mustache - https://plugins.jetbrains.com/plugin/6884-handlebars-mustache/
# Markdown Navigator - https://plugins.jetbrains.com/plugin/7896-markdown-navigator/
# PHP composer.json support - https://plugins.jetbrains.com/plugin/7631-php-composer-json-support/
# PHP Advanced AutoComplete - https://plugins.jetbrains.com/plugin/7276-php-advanced-autocomplete/

[[Category:Developer tools|PhpStorm]]

Setting up PhpStorm

2022-04-16T15:43:01Z

Mina: /* General settings */

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===

Do not install Java manually, download a PhpStorm package with bundled java instead.

==General settings==

* Uncheck "Missing @throws tag(s)" setting in "Preferences / Editor / Inspections / PHP / PHPDoc"
* Check "Strip trailing whitespace on Modified Lines" in "Preferences / Editor / General"
* Check "Show line numbers" in "Preferences / Editor / Appearance"
* Add Moodle database prefix by create file .phpstorm.meta.php in the project root directory, put the code below to enable PhpStorm recognized {table_name} as Database table:
<syntaxhighlight lang="php">
<?php

namespace PHPSTORM_META {
override(
// Virtual function to indicate that all SQL
// injections will have the following replacement rules.
sql_injection_subst(),
map([
'{' => "mdl_", // all `{` in injected SQL strings will be replaced with a prefix
'}' => '', // all `}` will be replaced with an empty string
]));
}
</syntaxhighlight>

==Bug tracker integration==

* Add tracker linking in "Preferences / Version control / Issue Navigation"
* Set Issue ID to "MDL-\d+|CONTRIB-\d+|MOBILE-\d+|MDLSITE-d+|MDLQA-\d+|UX-\d+|MDLNET-\d+|WPQA-\d+" and Issue link to "https://tracker.moodle.org/browse/$0" or just click on 'add Jira pattern' and paste "https://tracker.moodle.org"

==Code formatting==

* Setup coding style to use all rules from [[Coding style]] in "Preferences / Project Settings / Code Style / PHP" (or simply import from https://github.com/enovation/moodle-utils/blob/master/phpstorm-config/Moodle.xml) - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste.
* Set line separator to "Unix and OS X (\n)" in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Tips & Tricks==

* Use <syntaxhighlight lang="php">/** @var admin_root $ADMIN */</syntaxhighlight> to autofill $ADMIN->...
* Remove SQL syntax inspection errors for Moodle tables surrounded by curly brackets (like: <syntaxhighlight lang="php">SELECT * FROM {user}</syntaxhighlight>) by adding <syntaxhighlight lang="php">\{(\w+)\}</syntaxhighlight> to Tools > Databases > user parameters
(more info: https://blog.jetbrains.com/phpstorm/2014/11/database-language-injection-configuration/ , and a "feature request" to improve it: https://youtrack.jetbrains.com/issue/WI-4123 )
* You can deactivate warnings for specific exceptions (in particular the coding_exception, which is unlikely to be catched in your code) by going to Settings > PHP and add them to 'Unchecked Exceptions' under the 'Analysis' tab

==Moodle code checker==
Follow the instructions in the [https://github.com/moodlehq/moodle-local_codechecker/blob/master/README.md#ide-integration README]

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

==Javascript Development==
You can work on Javascript development by add Grunt configuration:
# Install Watchman - https://facebook.github.io/watchman/docs/install.html
# From the main Moodle directory open terminal and run:
<syntaxhighlight lang="shell">
npm install -g grunt-cli
npm install
</syntaxhighlight>
# Open "Edit configuration"
# Add new Grunt Task
## Verify that the node version is set with proper version for the current Moodle version
## In Tasks select watch
# Save the Grunt task
# Verify that in config.php the setting is not comment
<syntaxhighlight lang="php">
$CFG->cachejs = false;
</syntaxhighlight>
# Click on run icon
# happy Javascript development

==Debugging with Xdebug with docker containers==

This is very helpful when developing locally and you need to go step by step on the execution path of something of your interest.

If you're using [https://github.com/moodlehq/moodle-docker moodle-docker], please refer to its section about [https://github.com/moodlehq/moodle-docker#using-xdebug-for-live-debugging live debugging] before taking this section. If you are using a custom docker container, the web server container should be based on Debian-like to have the following instructions compatible.

These are the steps for configuring Xdebug to live debugging your code:

# Be sure containers are stopped.
# If you're using Docker on Mac or Windows, you can omit this step. So, only if you're using Docker on linux: Create a file named `add-host.docker.internal-to-etc-hosts` with execution rights on the Moodle root:
<syntaxhighlight lang="php">
#!/bin/bash
apt update
apt install -y iproute2
apt clean
apt auto-clean
HOST_DOMAIN="host.docker.internal"
ping -q -c1 $HOST_DOMAIN > /dev/null 2>&1
if [ $? -ne 0 ]; then
HOST_IP=$(ip route | awk 'NR==1 {print $3}')
echo -e "$HOST_IP\t$HOST_DOMAIN" >> /etc/hosts
fi
</syntaxhighlight>
# Edit the <syntaxhighlight lang="php">base.yml</syntaxhighlight> from the moodle-docker root (or equivalent from your custom docker container) to append these lines into the <syntaxhighlight lang="php">webserver: environment:</syntaxhighlight> section:
<syntaxhighlight lang="php">
XDEBUG_CONFIG:
idekey=phpstorm
remote_enable=1
remote_mode=req
remote_port=9000
remote_host=host.docker.internal
remote_connect_back=0
PHP_IDE_CONFIG:
serverName=moodle-local
</syntaxhighlight>
# The result for the <syntaxhighlight lang="php">webserver</syntaxhighlight> service should be like this (this example is from moodle-docker):
<syntaxhighlight lang="php">
webserver:
image: "moodlehq/moodle-php-apache:${MOODLE_DOCKER_PHP_VERSION}"
depends_on:
- db
volumes:
- "${MOODLE_DOCKER_WWWROOT}:/var/www/html"
- "${ASSETDIR}/web/apache2_faildumps.conf:/etc/apache2/conf-enabled/apache2_faildumps.conf"
environment:
MOODLE_DOCKER_DBTYPE: pgsql
MOODLE_DOCKER_DBNAME: moodle
MOODLE_DOCKER_DBUSER: moodle
MOODLE_DOCKER_DBPASS: "m@0dl3ing"
MOODLE_DOCKER_BROWSER: firefox
MOODLE_DOCKER_WEB_HOST: "${MOODLE_DOCKER_WEB_HOST}"
XDEBUG_CONFIG:
idekey=phpstorm
remote_enable=1
remote_mode=req
remote_port=9000
remote_host=host.docker.internal
remote_connect_back=0
PHP_IDE_CONFIG:
serverName=moodle-local
</syntaxhighlight>
# Start the moodle-docker containers, or your custom ones.
# Only if you're using Docker on linux: From a PhpStorm terminal, run: <syntaxhighlight lang="php">docker exec -it moodledocker_webserver_1 ./add-host.docker.internal-to-etc-hosts</syntaxhighlight>. You have to see how packages are installed.
# In any type of host (Mac, Windows or linux): Check that <syntaxhighlight lang="php">/etc/hosts</syntaxhighlight> has a line with <syntaxhighlight lang="php">host.docker.internal</syntaxhighlight>. You can do that with the command <syntaxhighlight lang="php">docker exec -it moodledocker_webserver_1 cat /etc/hosts</syntaxhighlight> (if you have a custom container name, use the name for the webserver container). The result should be something like this:
<syntaxhighlight lang="php">
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.20.0.6 17dff32616ac
172.20.0.1 host.docker.internal
</syntaxhighlight>
# Go to your PhpStorm and go to <syntaxhighlight lang="php">Run -> Edit configurations</syntaxhighlight> and select new <syntaxhighlight lang="php">PHP Remove Debug</syntaxhighlight>
# Name: "xdebug localhost" (or what you want to)
# Configuration: check "Filter debug connection by IDE key"
# IDE key(session id): "phpstorm"
# Define a new server:
# Name: must be "moodle-local"
# Host: localhost
# Port: must be the port you're using for the web server.
# Debugger: use the default (Xdebug)
# Check "Use path mappings (...)"
# Set for your "Project files" Moodle root the "Absolute path on the server" as "/var/www/html"
# Apply and OK on this screen. This screen will be closed.
# Apply and OK on the next screen. Settings screen will be closed.
# Now, test that live debugging works. To do so, please:
# Put a breakpoint on /index.php file.
# Press telephone icon with a red symbol with title "Start listening for PHP Debug Connections": telephone should appear with some waves now.
# Open your browser and open your localhost Moodle site.
# Happy debugging ;-)

Final note: Every time you start the webserver container, ONLY if you're using a linux host, you have to run the script for adding the host.docker.internal.
Final note 2: This method also works if your docker containers are in a different host from localhost: you just need to specify the proper server name and port.
Final note 3: This configuration also allows you to debug CLI scripts.

==Useful plugins==

# Php Inspections (EA Extended) - https://plugins.jetbrains.com/plugin/7622-php-inspections-ea-extended-/
# SonarLint - https://plugins.jetbrains.com/plugin/7973-sonarlint/
# Diff / Patch File Support - https://plugins.jetbrains.com/plugin/11957-diff--patch-file-support/
# Handlebars/Mustache - https://plugins.jetbrains.com/plugin/6884-handlebars-mustache/
# Markdown Navigator - https://plugins.jetbrains.com/plugin/7896-markdown-navigator/
# PHP composer.json support - https://plugins.jetbrains.com/plugin/7631-php-composer-json-support/
# PHP Advanced AutoComplete - https://plugins.jetbrains.com/plugin/7276-php-advanced-autocomplete/

[[Category:Developer tools|PhpStorm]]

Setting up PhpStorm

2022-04-16T15:42:48Z

Mina: /* General settings */ Update settings

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===

Do not install Java manually, download a PhpStorm package with bundled java instead.

==General settings==

* Uncheck "Missing @throws tag(s)" setting in "Preferences / Editor / Inspections / PHP / PHPDoc"
* Check "Strip trailing whitespace on Modified Lines" in "Preferences / Editor / General"
* Check "Show line numbers" in "Preferences / Editor / Appearance"
* Add Moodle database prefix by create file .phpstorm.meta.php in the project root directory, put the code below to enable PhpStorm recognized {table_name} as Database table:
<syntaxhighlight lang="php">
<?php

namespace PHPSTORM_META {
override(
// Virtual function to indicate that all SQL
// injections will have the following replacement rules.
sql_injection_subst(),
map([
'{' => "mdl_", // all `{` in injected SQL strings will be replaced with a prefix
'}' => '', // all `}` will be replaced with an empty string
]));
}
</syntaxhighlight>

==Bug tracker integration==

* Add tracker linking in "Preferences / Version control / Issue Navigation"
* Set Issue ID to "MDL-\d+|CONTRIB-\d+|MOBILE-\d+|MDLSITE-d+|MDLQA-\d+|UX-\d+|MDLNET-\d+|WPQA-\d+" and Issue link to "https://tracker.moodle.org/browse/$0" or just click on 'add Jira pattern' and paste "https://tracker.moodle.org"

==Code formatting==

* Setup coding style to use all rules from [[Coding style]] in "Preferences / Project Settings / Code Style / PHP" (or simply import from https://github.com/enovation/moodle-utils/blob/master/phpstorm-config/Moodle.xml) - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste.
* Set line separator to "Unix and OS X (\n)" in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Tips & Tricks==

* Use <syntaxhighlight lang="php">/** @var admin_root $ADMIN */</syntaxhighlight> to autofill $ADMIN->...
* Remove SQL syntax inspection errors for Moodle tables surrounded by curly brackets (like: <syntaxhighlight lang="php">SELECT * FROM {user}</syntaxhighlight>) by adding <syntaxhighlight lang="php">\{(\w+)\}</syntaxhighlight> to Tools > Databases > user parameters
(more info: https://blog.jetbrains.com/phpstorm/2014/11/database-language-injection-configuration/ , and a "feature request" to improve it: https://youtrack.jetbrains.com/issue/WI-4123 )
* You can deactivate warnings for specific exceptions (in particular the coding_exception, which is unlikely to be catched in your code) by going to Settings > PHP and add them to 'Unchecked Exceptions' under the 'Analysis' tab

==Moodle code checker==
Follow the instructions in the [https://github.com/moodlehq/moodle-local_codechecker/blob/master/README.md#ide-integration README]

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

==Javascript Development==
You can work on Javascript development by add Grunt configuration:
# Install Watchman - https://facebook.github.io/watchman/docs/install.html
# From the main Moodle directory open terminal and run:
<syntaxhighlight lang="shell">
npm install -g grunt-cli
npm install
</syntaxhighlight>
# Open "Edit configuration"
# Add new Grunt Task
## Verify that the node version is set with proper version for the current Moodle version
## In Tasks select watch
# Save the Grunt task
# Verify that in config.php the setting is not comment
<syntaxhighlight lang="php">
$CFG->cachejs = false;
</syntaxhighlight>
# Click on run icon
# happy Javascript development

==Debugging with Xdebug with docker containers==

This is very helpful when developing locally and you need to go step by step on the execution path of something of your interest.

If you're using [https://github.com/moodlehq/moodle-docker moodle-docker], please refer to its section about [https://github.com/moodlehq/moodle-docker#using-xdebug-for-live-debugging live debugging] before taking this section. If you are using a custom docker container, the web server container should be based on Debian-like to have the following instructions compatible.

These are the steps for configuring Xdebug to live debugging your code:

# Be sure containers are stopped.
# If you're using Docker on Mac or Windows, you can omit this step. So, only if you're using Docker on linux: Create a file named `add-host.docker.internal-to-etc-hosts` with execution rights on the Moodle root:
<syntaxhighlight lang="php">
#!/bin/bash
apt update
apt install -y iproute2
apt clean
apt auto-clean
HOST_DOMAIN="host.docker.internal"
ping -q -c1 $HOST_DOMAIN > /dev/null 2>&1
if [ $? -ne 0 ]; then
HOST_IP=$(ip route | awk 'NR==1 {print $3}')
echo -e "$HOST_IP\t$HOST_DOMAIN" >> /etc/hosts
fi
</syntaxhighlight>
# Edit the <syntaxhighlight lang="php">base.yml</syntaxhighlight> from the moodle-docker root (or equivalent from your custom docker container) to append these lines into the <syntaxhighlight lang="php">webserver: environment:</syntaxhighlight> section:
<syntaxhighlight lang="php">
XDEBUG_CONFIG:
idekey=phpstorm
remote_enable=1
remote_mode=req
remote_port=9000
remote_host=host.docker.internal
remote_connect_back=0
PHP_IDE_CONFIG:
serverName=moodle-local
</syntaxhighlight>
# The result for the <syntaxhighlight lang="php">webserver</syntaxhighlight> service should be like this (this example is from moodle-docker):
<syntaxhighlight lang="php">
webserver:
image: "moodlehq/moodle-php-apache:${MOODLE_DOCKER_PHP_VERSION}"
depends_on:
- db
volumes:
- "${MOODLE_DOCKER_WWWROOT}:/var/www/html"
- "${ASSETDIR}/web/apache2_faildumps.conf:/etc/apache2/conf-enabled/apache2_faildumps.conf"
environment:
MOODLE_DOCKER_DBTYPE: pgsql
MOODLE_DOCKER_DBNAME: moodle
MOODLE_DOCKER_DBUSER: moodle
MOODLE_DOCKER_DBPASS: "m@0dl3ing"
MOODLE_DOCKER_BROWSER: firefox
MOODLE_DOCKER_WEB_HOST: "${MOODLE_DOCKER_WEB_HOST}"
XDEBUG_CONFIG:
idekey=phpstorm
remote_enable=1
remote_mode=req
remote_port=9000
remote_host=host.docker.internal
remote_connect_back=0
PHP_IDE_CONFIG:
serverName=moodle-local
</syntaxhighlight>
# Start the moodle-docker containers, or your custom ones.
# Only if you're using Docker on linux: From a PhpStorm terminal, run: <syntaxhighlight lang="php">docker exec -it moodledocker_webserver_1 ./add-host.docker.internal-to-etc-hosts</syntaxhighlight>. You have to see how packages are installed.
# In any type of host (Mac, Windows or linux): Check that <syntaxhighlight lang="php">/etc/hosts</syntaxhighlight> has a line with <syntaxhighlight lang="php">host.docker.internal</syntaxhighlight>. You can do that with the command <syntaxhighlight lang="php">docker exec -it moodledocker_webserver_1 cat /etc/hosts</syntaxhighlight> (if you have a custom container name, use the name for the webserver container). The result should be something like this:
<syntaxhighlight lang="php">
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.20.0.6 17dff32616ac
172.20.0.1 host.docker.internal
</syntaxhighlight>
# Go to your PhpStorm and go to <syntaxhighlight lang="php">Run -> Edit configurations</syntaxhighlight> and select new <syntaxhighlight lang="php">PHP Remove Debug</syntaxhighlight>
# Name: "xdebug localhost" (or what you want to)
# Configuration: check "Filter debug connection by IDE key"
# IDE key(session id): "phpstorm"
# Define a new server:
# Name: must be "moodle-local"
# Host: localhost
# Port: must be the port you're using for the web server.
# Debugger: use the default (Xdebug)
# Check "Use path mappings (...)"
# Set for your "Project files" Moodle root the "Absolute path on the server" as "/var/www/html"
# Apply and OK on this screen. This screen will be closed.
# Apply and OK on the next screen. Settings screen will be closed.
# Now, test that live debugging works. To do so, please:
# Put a breakpoint on /index.php file.
# Press telephone icon with a red symbol with title "Start listening for PHP Debug Connections": telephone should appear with some waves now.
# Open your browser and open your localhost Moodle site.
# Happy debugging ;-)

Final note: Every time you start the webserver container, ONLY if you're using a linux host, you have to run the script for adding the host.docker.internal.
Final note 2: This method also works if your docker containers are in a different host from localhost: you just need to specify the proper server name and port.
Final note 3: This configuration also allows you to debug CLI scripts.

==Useful plugins==

# Php Inspections (EA Extended) - https://plugins.jetbrains.com/plugin/7622-php-inspections-ea-extended-/
# SonarLint - https://plugins.jetbrains.com/plugin/7973-sonarlint/
# Diff / Patch File Support - https://plugins.jetbrains.com/plugin/11957-diff--patch-file-support/
# Handlebars/Mustache - https://plugins.jetbrains.com/plugin/6884-handlebars-mustache/
# Markdown Navigator - https://plugins.jetbrains.com/plugin/7896-markdown-navigator/
# PHP composer.json support - https://plugins.jetbrains.com/plugin/7631-php-composer-json-support/
# PHP Advanced AutoComplete - https://plugins.jetbrains.com/plugin/7276-php-advanced-autocomplete/

[[Category:Developer tools|PhpStorm]]

Moodle versions

2020-07-25T09:34:54Z

Mina: /* Releases */ Fix link and date

==Moodle versions and branches==

Understanding the Moodle versioning scheme will help you when using our repositories to get your code (e.g. for an [[:en:Upgrading|upgrade]]). Knowing the correct versions is also very useful when reporting bugs in our [http://tracker.moodle.org tracker].

[[Image:versions.png|thumb|left|668px|Schema of Moodle source code branches, versions and maturity levels]]
<br clear="all" />

== Major and minor versions ==

Moodle version numbers consist of three numbers separated by a dot, for example 1.9.11 or 2.0.2. The first two numbers, like 1.9 or 2.0, represent the ''major version''. The third number distinguishes ''minor versions'' within the same major version. When a new major version is released, it starts with the minor version set to 0 (zero). So Moodle 2.0.1 was the first minor update of Moodle 2.0.0.

Generally, the Moodle HQ team maintains the two most recent major versions of Moodle (a notable exception to the rule was for Moodle 1.9 which was supported much longer).

== Versions and branches ==

Moodle developers use the source code management (SCM) system ''''Git'''' to track changes in the code. As in many SCMs, the history of changes in Git is represented via so called branches. You can consider a branch as a labeled sequence of source code changes.

There is a branch created for every major version of Moodle. All Moodle 1.9 versions come from MOODLE_19_STABLE branch and all Moodle 2.0 versions come from MOODLE_20_STABLE branch. There is also a main development branch called master that holds the changes for the next future version. At the moment, the changes on the master branch will be included in Moodle 2.1 release.

== Releases ==

Since version 2.0, Moodle aims to release the new major version every six months or so. See [[Roadmap]] page for a schedule.

Minor versions are released every two months, including both bugs and security issues fixed. See [[Releases#General release calendar|Releases]] page for more details and information.

In the meantime between two releases, Moodle HQ team publish updates for the most recent stable versions. These updates are published every week, usually on Thursday. They are known as ''weekly builds'' and are identified by a small increment in the version and a build date like [https://git.moodle.org/gw?p=moodle.git;a=commitdiff;h=d8b0be3eb38b8b7991af470776cfb15d30d43de6 20200723]. That is a timestamp in a form YYYYMMDD when the weekly build was released. These weekly builds are labelled with a version number suffixed with a plus sign. So 3.9.1+ denotes some weekly build extending the 3.9.1 minor release.

== Source code maturity levels ==

During its life cycle, the Moodle code branch goes through several maturity levels.
* At the beginning, the branch is considered as being in ''alpha'' state. During this period, new features are added to the branch. API and database structure may change as needed. These versions are intended mainly for developers as nothing is guaranteed (the version may or may not install and upgrade, for example).
* When it is decided that no new feature will be added to the branch (so called feature freeze), ''beta'' maturity level is reached. Developers focus on testing, bugs fixing and stabilizing the branch.
* When all known critical and blocker bugs are fixed and no new bugs are reported for some time of testing, a preview version of the branch can be released as so called release candidate. When the first release candidate version (RC1) has been published, ''release candidate'' maturity level is reached. During this period, several RC versions can be issued, for example 2.1RC1, 2.1RC2, 2.1RC3 etc.
* Finally, the new major version is released and the branch reaches ''stable'' maturity level. From now on, the database structure and API do not change on this branch. A corresponding MOODLE_xx_STABLE is created and minor versions and weekly builds are created off it.

==Version numbers==

Each plugin's version.php file can specify a minimum version of Moodle required for the plugin to work, for example

$plugin->version = 2011080200;
$plugin->requires = 2011070101;

For the version numbers related to each release, see the [[Releases]] page.

==How to increment version numbers in core==

In Moodle core, when we branch from master, we also branch version numbers. That means that no version number in a stable branch should ever be higher than on master (or a higher branched version).

The version number is constructed as '''YYYYMMDDRR.XX'''.

* '''YYYYMMDD''' is the date of the branching point. If on master, a branch has not happened, so it should be set to the current date. Otherwise it should not be changed (left as it was)
* '''RR''' is the release increment. This is the incremental counter for changes on a single branch or day (if in master).
* '''XX''' is the micro increment. This 'fraction increment' was introduced when after we realised that it might be possible to have more than 99 upgrade steps on a stable branch (in the RR increment). It tends to only be used in the main version number file.

===Rules for stable branches===

* If a 'micro increment' (.XX) exists
** Developers should only increment the 'micro increment' 'XX'
** The integration team reserve the use of 'RR' to branch between point releases.
* If a 'micro increment' (.XX) does not exist
** Please increment the RR.

===Rules for master===
* You must increment the whole version number to the current date.
* So, on 6th February 2013, the version number is set to: '''2013020600.00'''

===Why we branch versions ===
Imagine the following problem scenario:
# Moodle 2.4 is released, mod_forum is set to version 2012120300
# In master only, Eloy updates drops a DB field in an upgrade step and sets the moodle version to 2013010100
# In 2.4.1 and master, Dan fixes a problem in a capability definition and sets the version in both branches to 2013010200. (note: Oh no! we've incorrectly changed the branching date for the entire future 2.4.x!)
# Moodle 2.5 is released and the mod_forum is set to version 2013060100
# After the release, Helen updates her Moodle from Moodle 2.4.1 to 2.5.

The implications of Dan changing the 2.4.x version to 2013010200 in step 3, means that Eloy's upgrade step from 2 will never get run. '''This is very bad!'''

===I know that there are no changes between STABLE and master, can I set the version number as the same? ===
Not for core plugins, sorry. There are too many developers working on the same code and it prevents accidents if we avoid doing this for core.

== See also ==

* [[Releases]]
* [[:en:Git for Administrators|Git for Administrators]]
* http://download.moodle.org

[[es:Versiones de Moodle]]

version.php

2020-02-05T21:53:53Z

Mina: Add space to cope with coding style

This is an essential file expected to be located in the root directory of the plugin.

It contains a number of properties, which are used during the plugin installation and upgrade process. It allows to make sure the plugin is compatible with the given Moodle site, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note:''' There was an exception for [[Activity modules]]. In the past, activity modules used <tt>$module-></tt> instead of <tt>$plugin-></tt> in their version.php files. The <tt>$plugin-></tt> notation support for activity modules was added in Moodle 2.5 (MDL-38121) and became recommended. Support for legacy <tt>$module-></tt> was dropped in Moodle 3.0 (MDL-43896).

'''Note:''' Support for <tt>$plugin->supported =</tt> and <tt>$plugin->incompatible =</tt> was added in Moodle 3.9 (MDL-59562).

== Plugin version properties ==

{| class="nicetable"
|-
! Property
! Type
! Status
! Description and example
|- style="vertical-align:top"
| style="min-width:200px" | '''$plugin->component'''
| string
| required<sup>*</sup>
| The full [[Frankenstyle|frankenstyle]] component name in the form of plugintype_pluginname. It is used during the installation and upgrade process for diagnostics and validation purposes to make sure the plugin code has been deployed to the correct location within the Moodle code tree.

<nowiki>*</nowiki>) Required since Moodle 3.0, strongly recommended for earlier versions (MDL-48494).

<code php>$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.</code>
|- style="vertical-align:top;"
| '''$plugin->version'''
| integer
| required
| The version number of the plugin. The format is partially date based with the form YYYYMMDDXX where XX is an incremental counter for the given year (YYYY), month (MM) and date (DD) of the plugin version's release. Every new plugin version must have this number increased in this file, which is detected by Moodle core and the upgrade process is triggered.

In case of linear development (i.e. there is just one branch of the plugin maintained), the XX counter should stay with the initial 00 value unless multiple versions are released on the same date.

If multiple stable branches of the plugin are maintained, the date part YYYYMMDD should be frozen at the branch forking date and the XX is used for incrementing the value on the given stable branch (allowing up to 100 updates on the given stable branch). The key point is that the version number is always increased both horizontally (within the same stable branch, more recent updates have higher XX than any previous one) and vertically (between any two stable branches, the more recent branch has YYYYMMDD00 higher than the older stable branch). Pay attention to this. It's easy to mess up and hard to fix.

See [https://moodle.org/mod/forum/discuss.php?d=275635#p1184986] for an example of versioning scheme on multiple branches.

<code php>$plugin->version = 2014052000; // Plugin released on 20th May 2014.</code>
|- style="vertical-align:top;"
| '''$plugin->requires'''
| integer
| recommended
| Specifies the minimum version number of Moodle core that this plugin requires. It is not possible to install it to earlier Moodle version. Moodle core's version number is defined in the file version.php located in Moodle root directory, in the <tt>$version</tt> variable.

Note that Moodle core extends the version numbering scheme and has inbuilt support for decimal versioning (such as <tt>$version = 2014051200.01;</tt>). The decimal part is used for incremental (weekly) builds. Plugins should not rely on a particular weekly build so they use just the whole number part of the Moodle core's version in this field.

See [[Releases]] for the full list of Moodle core version numbers.

<code php>$plugin->requires = 2014051200; // Moodle 2.7.0 is required.</code>
|- style="vertical-align:top;"
| '''$plugin->supported'''
| array of two ascending integers
| optional
| Specifies a range of branch numbers of supported versions, inclusive. Moodle versions that are outside of this range will produce a message notifying at install time, but will allow for installation.

<code php>$plugin->supported = [37, 39]; // Moodle 3.7.x, 3.8.x and 3.9.x are supported.</code>
|- style="vertical-align:top;"
| '''$plugin->incompatible'''
| integer
| optional
| Specifies the latest incompatible Moodle major branch. Any Moodle versions including and above this will be prevented from installing the plugin, and a message will be given when attempting installation.

<code php>$plugin->incompatible = 36; // Moodle 3.6.x and later are incompatible.</code>
|- style="vertical-align:top;"
| '''$plugin->cron'''
| integer
| discouraged*
| Allows to throttle the plugin's cron function calls. The set value represents a minimal required gap in seconds between two calls of the plugin's cron function. Note that the cron function is not supported in all plugin types (also note that, while the cron function '''is''' supported for authentication plugins, it is run every time the cron script runs, regardless of this value in version.php). This value is stored in the database. After changing this value, the version number must be incremented. For activity modules, if this value is not set or 0 the cron function is disabled.

<nowiki>*</nowiki>) Starting with Moodle 2.7, plugin developers are encouraged to use the [[Task API|scheduled task API]] instead of the cron function feature.

<code php>$plugin->cron = 300; // Do not execute this plugin's cron more often than every five minutes.</code>
|- style="vertical-align:top;"
| '''$plugin->maturity'''
| enum
| recommended
| Declares the maturity level of this plugin version, that is how stable it is. This affects the [[:en:Available update notifications|available update notifications]] feature in Moodle. Administrators can configure their site so that they are not notified about an available update unless it has certain maturity level declared.

Supported value is any of the predefined constants <tt>MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC</tt> or <tt>MATURITY_STABLE</tt>.

<code php>$plugin->maturity = MATURITY_STABLE; // This is considered as ready for production sites.</code>
|- style="vertical-align:top;"
| '''$plugin->release'''
| string
| recommended
| Human readable version name that should help to identify each release of the plugin. It can be anything you like although it is recommended to choose a pattern and stick with it. Usually it is a simple version like <tt>2.1</tt> but some plugin authors use more sophisticated schemes or follow the upstream release name if the plugin represents a wrapper for another program.

It is a good practise to tag the code in the source code management system for each plugin release and then make the tag names matching this release name.

<code php>$plugin->release = 'v2.7-r1'; // This is our first revision for Moodle 2.7.x branch.</code>
|- style="vertical-align:top;"
| '''$plugin->dependencies'''
| array
| optional
| Allows to declare explicit dependency on other plugin(s) for this plugin to work. Moodle core checks these declared dependencies and will not allow the plugin installation and/or upgrade until all dependencies are satisfied.

Each element in the array represents an dependency on another plugin. The key (string) in the array is the component (frankenstyle) name of the other plugin. The value (integer) is the version of the other plugin we require. The predefined constant <tt>ANY_VERSION</tt> can be used if we do not depend on a particular version (we just need the other plugin present).

<code php>$plugin->dependencies = array(
'mod_foo' => ANY_VERSION, // The Foo activity must be present (any version).
'enrol_bar' => 2014020300, // The Bar enrolment plugin version 2014020300 or higher must be present.
);</code>
|}

== File template ==

Here is a template for the plugin's version.php file to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* @package plugintype_pluginname
* @copyright 2020, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO;
$plugin->supported = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->incompatible = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = [
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
];
</code>

== See also ==

* [[Moodle versions]]

[[Category:Plugins]]

version.php

2020-01-19T11:51:55Z

Mina: /* Plugin version properties */ Add documentation about new `$plugin->supported` and `$plugin->incompatible` settings

This is an essential file expected to be located in the root directory of the plugin.

It contains a number of properties, which are used during the plugin installation and upgrade process. It allows to make sure the plugin is compatible with the given Moodle site, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note:''' There was an exception for [[Activity modules]]. In the past, activity modules used <tt>$module-></tt> instead of <tt>$plugin-></tt> in their version.php files. The <tt>$plugin-></tt> notation support for activity modules was added in Moodle 2.5 (MDL-38121) and became recommended. Support for legacy <tt>$module-></tt> was dropped in Moodle 3.0 (MDL-43896).

'''Note:''' Support for <tt>$plugin->supported =</tt> and <tt>$plugin->incompatible =</tt> was added in Moodle 3.9 (MDL-59562).

== Plugin version properties ==

{| class="nicetable"
|-
! Property
! Type
! Status
! Description and example
|- style="vertical-align:top"
| style="min-width:200px" | '''$plugin->component'''
| string
| required<sup>*</sup>
| The full [[Frankenstyle|frankenstyle]] component name in the form of plugintype_pluginname. It is used during the installation and upgrade process for diagnostics and validation purposes to make sure the plugin code has been deployed to the correct location within the Moodle code tree.

<nowiki>*</nowiki>) Required since Moodle 3.0, strongly recommended for earlier versions (MDL-48494).

<code php>$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.</code>
|- style="vertical-align:top;"
| '''$plugin->version'''
| integer
| required
| The version number of the plugin. The format is partially date based with the form YYYYMMDDXX where XX is an incremental counter for the given year (YYYY), month (MM) and date (DD) of the plugin version's release. Every new plugin version must have this number increased in this file, which is detected by Moodle core and the upgrade process is triggered.

In case of linear development (i.e. there is just one branch of the plugin maintained), the XX counter should stay with the initial 00 value unless multiple versions are released on the same date.

If multiple stable branches of the plugin are maintained, the date part YYYYMMDD should be frozen at the branch forking date and the XX is used for incrementing the value on the given stable branch (allowing up to 100 updates on the given stable branch). The key point is that the version number is always increased both horizontally (within the same stable branch, more recent updates have higher XX than any previous one) and vertically (between any two stable branches, the more recent branch has YYYYMMDD00 higher than the older stable branch). Pay attention to this. It's easy to mess up and hard to fix.

See [https://moodle.org/mod/forum/discuss.php?d=275635#p1184986] for an example of versioning scheme on multiple branches.

<code php>$plugin->version = 2014052000; // Plugin released on 20th May 2014.</code>
|- style="vertical-align:top;"
| '''$plugin->requires'''
| integer
| recommended
| Specifies the minimum version number of Moodle core that this plugin requires. It is not possible to install it to earlier Moodle version. Moodle core's version number is defined in the file version.php located in Moodle root directory, in the <tt>$version</tt> variable.

Note that Moodle core extends the version numbering scheme and has inbuilt support for decimal versioning (such as <tt>$version = 2014051200.01;</tt>). The decimal part is used for incremental (weekly) builds. Plugins should not rely on a particular weekly build so they use just the whole number part of the Moodle core's version in this field.

See [[Releases]] for the full list of Moodle core version numbers.

<code php>$plugin->requires = 2014051200; // Moodle 2.7.0 is required.</code>
|- style="vertical-align:top;"
| '''$plugin->supported'''
| array of two ascending integers
| optional
| Specifies a range of branch numbers of supported versions, inclusive. Moodle versions that are outside of this range will produce a message notifying at install time, but will allow for installation.

<code php>$plugin->supported = [37,39]; // Moodle 3.7.x, 3.8.x and 3.9.x are supported.</code>
|- style="vertical-align:top;"
| '''$plugin->incompatible'''
| integer
| optional
| Specifies the latest incompatible Moodle major branch. Any Moodle versions including and below this will be prevented from installing the plugin, and a message will be given when attempting installation.

<code php>$plugin->incompatible = 36; // Moodle 3.6.x and earlier are incompatible.</code>
|- style="vertical-align:top;"
| '''$plugin->cron'''
| integer
| discouraged*
| Allows to throttle the plugin's cron function calls. The set value represents a minimal required gap in seconds between two calls of the plugin's cron function. Note that the cron function is not supported in all plugin types (also note that, while the cron function '''is''' supported for authentication plugins, it is run every time the cron script runs, regardless of this value in version.php). This value is stored in the database. After changing this value, the version number must be incremented. For activity modules, if this value is not set or 0 the cron function is disabled.

<nowiki>*</nowiki>) Starting with Moodle 2.7, plugin developers are encouraged to use the [[Task API|scheduled task API]] instead of the cron function feature.

<code php>$plugin->cron = 300; // Do not execute this plugin's cron more often than every five minutes.</code>
|- style="vertical-align:top;"
| '''$plugin->maturity'''
| enum
| recommended
| Declares the maturity level of this plugin version, that is how stable it is. This affects the [[:en:Available update notifications|available update notifications]] feature in Moodle. Administrators can configure their site so that they are not notified about an available update unless it has certain maturity level declared.

Supported value is any of the predefined constants <tt>MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC</tt> or <tt>MATURITY_STABLE</tt>.

<code php>$plugin->maturity = MATURITY_STABLE; // This is considered as ready for production sites.</code>
|- style="vertical-align:top;"
| '''$plugin->release'''
| string
| recommended
| Human readable version name that should help to identify each release of the plugin. It can be anything you like although it is recommended to choose a pattern and stick with it. Usually it is a simple version like <tt>2.1</tt> but some plugin authors use more sophisticated schemes or follow the upstream release name if the plugin represents a wrapper for another program.

It is a good practise to tag the code in the source code management system for each plugin release and then make the tag names matching this release name.

<code php>$plugin->release = 'v2.7-r1'; // This is our first revision for Moodle 2.7.x branch.</code>
|- style="vertical-align:top;"
| '''$plugin->dependencies'''
| array
| optional
| Allows to declare explicit dependency on other plugin(s) for this plugin to work. Moodle core checks these declared dependencies and will not allow the plugin installation and/or upgrade until all dependencies are satisfied.

Each element in the array represents an dependency on another plugin. The key (string) in the array is the component (frankenstyle) name of the other plugin. The value (integer) is the version of the other plugin we require. The predefined constant <tt>ANY_VERSION</tt> can be used if we do not depend on a particular version (we just need the other plugin present).

<code php>$plugin->dependencies = array(
'mod_foo' => ANY_VERSION, // The Foo activity must be present (any version).
'enrol_bar' => 2014020300, // The Bar enrolment plugin version 2014020300 or higher must be present.
);</code>
|}

== File template ==

Here is a template for the plugin's version.php file to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* @package plugintype_pluginname
* @copyright 2020, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO;
$plugin->supported = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->incompatible = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = [
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
];
</code>

== See also ==

* [[Moodle versions]]

[[Category:Plugins]]

version.php

2020-01-19T11:26:56Z

Mina: /* File template */ Remove discouraged `$plugin->cron` setting from template

This is an essential file expected to be located in the root directory of the plugin.

It contains a number of properties, which are used during the plugin installation and upgrade process. It allows to make sure the plugin is compatible with the given Moodle site, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note:''' There was an exception for [[Activity modules]]. In the past, activity modules used <tt>$module-></tt> instead of <tt>$plugin-></tt> in their version.php files. The <tt>$plugin-></tt> notation support for activity modules was added in Moodle 2.5 (MDL-38121) and became recommended. Support for legacy <tt>$module-></tt> was dropped in Moodle 3.0 (MDL-43896).

'''Note:''' Support for <tt>$plugin->supported =</tt> and <tt>$plugin->incompatible =</tt> was added in Moodle 3.9 (MDL-59562).

== Plugin version properties ==

{| class="nicetable"
|-
! Property
! Type
! Status
! Description and example
|- style="vertical-align:top"
| style="min-width:200px" | '''$plugin->component'''
| string
| required<sup>*</sup>
| The full [[Frankenstyle|frankenstyle]] component name in the form of plugintype_pluginname. It is used during the installation and upgrade process for diagnostics and validation purposes to make sure the plugin code has been deployed to the correct location within the Moodle code tree.

<nowiki>*</nowiki>) Required since Moodle 3.0, strongly recommended for earlier versions (MDL-48494).

<code php>$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.</code>
|- style="vertical-align:top;"
| '''$plugin->version'''
| integer
| required
| The version number of the plugin. The format is partially date based with the form YYYYMMDDXX where XX is an incremental counter for the given year (YYYY), month (MM) and date (DD) of the plugin version's release. Every new plugin version must have this number increased in this file, which is detected by Moodle core and the upgrade process is triggered.

In case of linear development (i.e. there is just one branch of the plugin maintained), the XX counter should stay with the initial 00 value unless multiple versions are released on the same date.

If multiple stable branches of the plugin are maintained, the date part YYYYMMDD should be frozen at the branch forking date and the XX is used for incrementing the value on the given stable branch (allowing up to 100 updates on the given stable branch). The key point is that the version number is always increased both horizontally (within the same stable branch, more recent updates have higher XX than any previous one) and vertically (between any two stable branches, the more recent branch has YYYYMMDD00 higher than the older stable branch). Pay attention to this. It's easy to mess up and hard to fix.

See [https://moodle.org/mod/forum/discuss.php?d=275635#p1184986] for an example of versioning scheme on multiple branches.

<code php>$plugin->version = 2014052000; // Plugin released on 20th May 2014.</code>
|- style="vertical-align:top;"
| '''$plugin->requires'''
| integer
| recommended
| Specifies the minimum version number of Moodle core that this plugin requires. It is not possible to install it to earlier Moodle version. Moodle core's version number is defined in the file version.php located in Moodle root directory, in the <tt>$version</tt> variable.

Note that Moodle core extends the version numbering scheme and has inbuilt support for decimal versioning (such as <tt>$version = 2014051200.01;</tt>). The decimal part is used for incremental (weekly) builds. Plugins should not rely on a particular weekly build so they use just the whole number part of the Moodle core's version in this field.

See [[Releases]] for the full list of Moodle core version numbers.

<code php>$plugin->requires = 2014051200; // Moodle 2.7.0 is required.</code>
|- style="vertical-align:top;"
| '''$plugin->cron'''
| integer
| discouraged*
| Allows to throttle the plugin's cron function calls. The set value represents a minimal required gap in seconds between two calls of the plugin's cron function. Note that the cron function is not supported in all plugin types (also note that, while the cron function '''is''' supported for authentication plugins, it is run every time the cron script runs, regardless of this value in version.php). This value is stored in the database. After changing this value, the version number must be incremented. For activity modules, if this value is not set or 0 the cron function is disabled.

<nowiki>*</nowiki>) Starting with Moodle 2.7, plugin developers are encouraged to use the [[Task API|scheduled task API]] instead of the cron function feature.

<code php>$plugin->cron = 300; // Do not execute this plugin's cron more often than every five minutes.</code>
|- style="vertical-align:top;"
| '''$plugin->maturity'''
| enum
| recommended
| Declares the maturity level of this plugin version, that is how stable it is. This affects the [[:en:Available update notifications|available update notifications]] feature in Moodle. Administrators can configure their site so that they are not notified about an available update unless it has certain maturity level declared.

Supported value is any of the predefined constants <tt>MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC</tt> or <tt>MATURITY_STABLE</tt>.

<code php>$plugin->maturity = MATURITY_STABLE; // This is considered as ready for production sites.</code>
|- style="vertical-align:top;"
| '''$plugin->release'''
| string
| recommended
| Human readable version name that should help to identify each release of the plugin. It can be anything you like although it is recommended to choose a pattern and stick with it. Usually it is a simple version like <tt>2.1</tt> but some plugin authors use more sophisticated schemes or follow the upstream release name if the plugin represents a wrapper for another program.

It is a good practise to tag the code in the source code management system for each plugin release and then make the tag names matching this release name.

<code php>$plugin->release = 'v2.7-r1'; // This is our first revision for Moodle 2.7.x branch.</code>
|- style="vertical-align:top;"
| '''$plugin->dependencies'''
| array
| optional
| Allows to declare explicit dependency on other plugin(s) for this plugin to work. Moodle core checks these declared dependencies and will not allow the plugin installation and/or upgrade until all dependencies are satisfied.

Each element in the array represents an dependency on another plugin. The key (string) in the array is the component (frankenstyle) name of the other plugin. The value (integer) is the version of the other plugin we require. The predefined constant <tt>ANY_VERSION</tt> can be used if we do not depend on a particular version (we just need the other plugin present).

<code php>$plugin->dependencies = array(
'mod_foo' => ANY_VERSION, // The Foo activity must be present (any version).
'enrol_bar' => 2014020300, // The Bar enrolment plugin version 2014020300 or higher must be present.
);</code>
|}

== File template ==

Here is a template for the plugin's version.php file to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* @package plugintype_pluginname
* @copyright 2020, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO;
$plugin->supported = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->incompatible = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = [
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
];
</code>

== See also ==

* [[Moodle versions]]

[[Category:Plugins]]

version.php

2020-01-19T11:25:02Z

Mina: Note added about new settings `$plugin->supported` and `$plugin->incompatible`

This is an essential file expected to be located in the root directory of the plugin.

It contains a number of properties, which are used during the plugin installation and upgrade process. It allows to make sure the plugin is compatible with the given Moodle site, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note:''' There was an exception for [[Activity modules]]. In the past, activity modules used <tt>$module-></tt> instead of <tt>$plugin-></tt> in their version.php files. The <tt>$plugin-></tt> notation support for activity modules was added in Moodle 2.5 (MDL-38121) and became recommended. Support for legacy <tt>$module-></tt> was dropped in Moodle 3.0 (MDL-43896).

'''Note:''' Support for <tt>$plugin->supported =</tt> and <tt>$plugin->incompatible =</tt> was added in Moodle 3.9 (MDL-59562).

== Plugin version properties ==

{| class="nicetable"
|-
! Property
! Type
! Status
! Description and example
|- style="vertical-align:top"
| style="min-width:200px" | '''$plugin->component'''
| string
| required<sup>*</sup>
| The full [[Frankenstyle|frankenstyle]] component name in the form of plugintype_pluginname. It is used during the installation and upgrade process for diagnostics and validation purposes to make sure the plugin code has been deployed to the correct location within the Moodle code tree.

<nowiki>*</nowiki>) Required since Moodle 3.0, strongly recommended for earlier versions (MDL-48494).

<code php>$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.</code>
|- style="vertical-align:top;"
| '''$plugin->version'''
| integer
| required
| The version number of the plugin. The format is partially date based with the form YYYYMMDDXX where XX is an incremental counter for the given year (YYYY), month (MM) and date (DD) of the plugin version's release. Every new plugin version must have this number increased in this file, which is detected by Moodle core and the upgrade process is triggered.

In case of linear development (i.e. there is just one branch of the plugin maintained), the XX counter should stay with the initial 00 value unless multiple versions are released on the same date.

If multiple stable branches of the plugin are maintained, the date part YYYYMMDD should be frozen at the branch forking date and the XX is used for incrementing the value on the given stable branch (allowing up to 100 updates on the given stable branch). The key point is that the version number is always increased both horizontally (within the same stable branch, more recent updates have higher XX than any previous one) and vertically (between any two stable branches, the more recent branch has YYYYMMDD00 higher than the older stable branch). Pay attention to this. It's easy to mess up and hard to fix.

See [https://moodle.org/mod/forum/discuss.php?d=275635#p1184986] for an example of versioning scheme on multiple branches.

<code php>$plugin->version = 2014052000; // Plugin released on 20th May 2014.</code>
|- style="vertical-align:top;"
| '''$plugin->requires'''
| integer
| recommended
| Specifies the minimum version number of Moodle core that this plugin requires. It is not possible to install it to earlier Moodle version. Moodle core's version number is defined in the file version.php located in Moodle root directory, in the <tt>$version</tt> variable.

Note that Moodle core extends the version numbering scheme and has inbuilt support for decimal versioning (such as <tt>$version = 2014051200.01;</tt>). The decimal part is used for incremental (weekly) builds. Plugins should not rely on a particular weekly build so they use just the whole number part of the Moodle core's version in this field.

See [[Releases]] for the full list of Moodle core version numbers.

<code php>$plugin->requires = 2014051200; // Moodle 2.7.0 is required.</code>
|- style="vertical-align:top;"
| '''$plugin->cron'''
| integer
| discouraged*
| Allows to throttle the plugin's cron function calls. The set value represents a minimal required gap in seconds between two calls of the plugin's cron function. Note that the cron function is not supported in all plugin types (also note that, while the cron function '''is''' supported for authentication plugins, it is run every time the cron script runs, regardless of this value in version.php). This value is stored in the database. After changing this value, the version number must be incremented. For activity modules, if this value is not set or 0 the cron function is disabled.

<nowiki>*</nowiki>) Starting with Moodle 2.7, plugin developers are encouraged to use the [[Task API|scheduled task API]] instead of the cron function feature.

<code php>$plugin->cron = 300; // Do not execute this plugin's cron more often than every five minutes.</code>
|- style="vertical-align:top;"
| '''$plugin->maturity'''
| enum
| recommended
| Declares the maturity level of this plugin version, that is how stable it is. This affects the [[:en:Available update notifications|available update notifications]] feature in Moodle. Administrators can configure their site so that they are not notified about an available update unless it has certain maturity level declared.

Supported value is any of the predefined constants <tt>MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC</tt> or <tt>MATURITY_STABLE</tt>.

<code php>$plugin->maturity = MATURITY_STABLE; // This is considered as ready for production sites.</code>
|- style="vertical-align:top;"
| '''$plugin->release'''
| string
| recommended
| Human readable version name that should help to identify each release of the plugin. It can be anything you like although it is recommended to choose a pattern and stick with it. Usually it is a simple version like <tt>2.1</tt> but some plugin authors use more sophisticated schemes or follow the upstream release name if the plugin represents a wrapper for another program.

It is a good practise to tag the code in the source code management system for each plugin release and then make the tag names matching this release name.

<code php>$plugin->release = 'v2.7-r1'; // This is our first revision for Moodle 2.7.x branch.</code>
|- style="vertical-align:top;"
| '''$plugin->dependencies'''
| array
| optional
| Allows to declare explicit dependency on other plugin(s) for this plugin to work. Moodle core checks these declared dependencies and will not allow the plugin installation and/or upgrade until all dependencies are satisfied.

Each element in the array represents an dependency on another plugin. The key (string) in the array is the component (frankenstyle) name of the other plugin. The value (integer) is the version of the other plugin we require. The predefined constant <tt>ANY_VERSION</tt> can be used if we do not depend on a particular version (we just need the other plugin present).

<code php>$plugin->dependencies = array(
'mod_foo' => ANY_VERSION, // The Foo activity must be present (any version).
'enrol_bar' => 2014020300, // The Bar enrolment plugin version 2014020300 or higher must be present.
);</code>
|}

== File template ==

Here is a template for the plugin's version.php file to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* @package plugintype_pluginname
* @copyright 2018, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO;
$plugin->supported = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->incompatible = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->cron = 0;
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = [
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
];
</code>

== See also ==

* [[Moodle versions]]

[[Category:Plugins]]

version.php

2020-01-19T11:16:28Z

Mina: /* File template */ Document new settings introduced by MDL-59562

This is an essential file expected to be located in the root directory of the plugin.

It contains a number of properties, which are used during the plugin installation and upgrade process. It allows to make sure the plugin is compatible with the given Moodle site, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note:''' There was an exception for [[Activity modules]]. In the past, activity modules used <tt>$module-></tt> instead of <tt>$plugin-></tt> in their version.php files. The <tt>$plugin-></tt> notation support for activity modules was added in Moodle 2.5 (MDL-38121) and became recommended. Support for legacy <tt>$module-></tt> was dropped in Moodle 3.0 (MDL-43896).

== Plugin version properties ==

{| class="nicetable"
|-
! Property
! Type
! Status
! Description and example
|- style="vertical-align:top"
| style="min-width:200px" | '''$plugin->component'''
| string
| required<sup>*</sup>
| The full [[Frankenstyle|frankenstyle]] component name in the form of plugintype_pluginname. It is used during the installation and upgrade process for diagnostics and validation purposes to make sure the plugin code has been deployed to the correct location within the Moodle code tree.

<nowiki>*</nowiki>) Required since Moodle 3.0, strongly recommended for earlier versions (MDL-48494).

<code php>$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.</code>
|- style="vertical-align:top;"
| '''$plugin->version'''
| integer
| required
| The version number of the plugin. The format is partially date based with the form YYYYMMDDXX where XX is an incremental counter for the given year (YYYY), month (MM) and date (DD) of the plugin version's release. Every new plugin version must have this number increased in this file, which is detected by Moodle core and the upgrade process is triggered.

In case of linear development (i.e. there is just one branch of the plugin maintained), the XX counter should stay with the initial 00 value unless multiple versions are released on the same date.

If multiple stable branches of the plugin are maintained, the date part YYYYMMDD should be frozen at the branch forking date and the XX is used for incrementing the value on the given stable branch (allowing up to 100 updates on the given stable branch). The key point is that the version number is always increased both horizontally (within the same stable branch, more recent updates have higher XX than any previous one) and vertically (between any two stable branches, the more recent branch has YYYYMMDD00 higher than the older stable branch). Pay attention to this. It's easy to mess up and hard to fix.

See [https://moodle.org/mod/forum/discuss.php?d=275635#p1184986] for an example of versioning scheme on multiple branches.

<code php>$plugin->version = 2014052000; // Plugin released on 20th May 2014.</code>
|- style="vertical-align:top;"
| '''$plugin->requires'''
| integer
| recommended
| Specifies the minimum version number of Moodle core that this plugin requires. It is not possible to install it to earlier Moodle version. Moodle core's version number is defined in the file version.php located in Moodle root directory, in the <tt>$version</tt> variable.

Note that Moodle core extends the version numbering scheme and has inbuilt support for decimal versioning (such as <tt>$version = 2014051200.01;</tt>). The decimal part is used for incremental (weekly) builds. Plugins should not rely on a particular weekly build so they use just the whole number part of the Moodle core's version in this field.

See [[Releases]] for the full list of Moodle core version numbers.

<code php>$plugin->requires = 2014051200; // Moodle 2.7.0 is required.</code>
|- style="vertical-align:top;"
| '''$plugin->cron'''
| integer
| discouraged*
| Allows to throttle the plugin's cron function calls. The set value represents a minimal required gap in seconds between two calls of the plugin's cron function. Note that the cron function is not supported in all plugin types (also note that, while the cron function '''is''' supported for authentication plugins, it is run every time the cron script runs, regardless of this value in version.php). This value is stored in the database. After changing this value, the version number must be incremented. For activity modules, if this value is not set or 0 the cron function is disabled.

<nowiki>*</nowiki>) Starting with Moodle 2.7, plugin developers are encouraged to use the [[Task API|scheduled task API]] instead of the cron function feature.

<code php>$plugin->cron = 300; // Do not execute this plugin's cron more often than every five minutes.</code>
|- style="vertical-align:top;"
| '''$plugin->maturity'''
| enum
| recommended
| Declares the maturity level of this plugin version, that is how stable it is. This affects the [[:en:Available update notifications|available update notifications]] feature in Moodle. Administrators can configure their site so that they are not notified about an available update unless it has certain maturity level declared.

Supported value is any of the predefined constants <tt>MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC</tt> or <tt>MATURITY_STABLE</tt>.

<code php>$plugin->maturity = MATURITY_STABLE; // This is considered as ready for production sites.</code>
|- style="vertical-align:top;"
| '''$plugin->release'''
| string
| recommended
| Human readable version name that should help to identify each release of the plugin. It can be anything you like although it is recommended to choose a pattern and stick with it. Usually it is a simple version like <tt>2.1</tt> but some plugin authors use more sophisticated schemes or follow the upstream release name if the plugin represents a wrapper for another program.

It is a good practise to tag the code in the source code management system for each plugin release and then make the tag names matching this release name.

<code php>$plugin->release = 'v2.7-r1'; // This is our first revision for Moodle 2.7.x branch.</code>
|- style="vertical-align:top;"
| '''$plugin->dependencies'''
| array
| optional
| Allows to declare explicit dependency on other plugin(s) for this plugin to work. Moodle core checks these declared dependencies and will not allow the plugin installation and/or upgrade until all dependencies are satisfied.

Each element in the array represents an dependency on another plugin. The key (string) in the array is the component (frankenstyle) name of the other plugin. The value (integer) is the version of the other plugin we require. The predefined constant <tt>ANY_VERSION</tt> can be used if we do not depend on a particular version (we just need the other plugin present).

<code php>$plugin->dependencies = array(
'mod_foo' => ANY_VERSION, // The Foo activity must be present (any version).
'enrol_bar' => 2014020300, // The Bar enrolment plugin version 2014020300 or higher must be present.
);</code>
|}

== File template ==

Here is a template for the plugin's version.php file to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* @package plugintype_pluginname
* @copyright 2018, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO;
$plugin->supported = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->incompatible = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->cron = 0;
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = [
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
];
</code>

== See also ==

* [[Moodle versions]]

[[Category:Plugins]]

Translating plugins

2019-04-25T10:23:10Z

Mina: /* Strings priority */ Fixed priority

{{Translation}}
==Looking for translated plugins in the Moodle plugins database==

* Almost all contributed plugins published in Moodle Plugins directory have been imported into [http://lang.moodle.org/ AMOS] and are ready to be translated.
* When a user is looking at the [https://moodle.org/plugins/ Moodle plugins database], in ' Description tab > Useful links section' there is a link to 'Contribute translation for (your preferred language)' that points to [http://lang.moodle.org/ AMOS].
* Have a look at an example for the very popular [https://moodle.org/plugins/view.php?plugin=mod_hotpot HotPot] plugin:

[[File:Link to Plugin translations in Moodle plugins database.png|300px]]

* You can click on the 'Contribute translation for (your preferred language)' link.
* '''CURRENTLY:''' If you do not have an AMOS account, you would have to 'Create a new account' by using the appropriate link.
* If you have a translator account in AMOS, you can use AMOS to contribute the translation.
* If you select all the language packs (except English fixes) and write 'pluginname' in the box for 'String identifier', AMOS will display the name of the plugin in all available translations.
* Make sure that you have selected the Moodle branch(es) that you are interested in (eg, 2.5 in the image below).

[[File:Plugins translations in AMOS.png|400px]]

* In the above example, there are a total of 123 different language packs registered in AMOS; 63 of these are missing a translation for HotPot, which means that there are 60 different language translations already available for the HotPot plugin, a fair number for this popular plugin :)
* When no translation is available for any/many language(s), the box named 'Translation' will be empty for those languages.
* If a plugin name has been translated, there is a fair chance (but no certainty) that this plugin has been (completely) translated into that language. You can change the settings in AMOS and check for yourself.

==Plugin translation priority==
* Please help Moodle users in other languages by translating your favourite plugins.
* Moodle has a continuously updated [https://moodle.org/plugins/report/index.php?report=favourites&p=0&l=50&s=favourited&d=DESC list of the most favourite plugins], which might be worth considering for translation :)
* You can find the plugins with the largest number of downloads in the last three months at [https://moodle.org/plugins/stats.php https://moodle.org/plugins/stats.php]. These are the plugins most likely to be most useful when translated to your language. It would probably be a good idea to translate them first.
* Moodle has a list of plugins that have received the [https://moodle.org/plugins/browse.php?list=award&id=1 Reviewers' choice award]. These are given by the plugins guardians and reviewers for particularly useful, well coded or otherwise interesting plugins. It would be very desirable/useful to have these translated.
* See the [https://moodle.org/mod/forum/discuss.php?d=325804 list of (year 2015) favorite plugins] by Gavin Henrick
* Special cases:
** All plugins with ''mobile'' in their name, and all [https://moodle.org/plugins/browse.php?list=set&id=62 server side plugins] to support the [https://docs.moodle.org/31/en/Moodle_Mobile Moodle mobile app]
** [https://moodle.org/plugins/local_moodlecloudsignup MoodleCloud strings] are used for accessing the [https://moodle.com/cloud/ MoodleCloud] free and paid hosting services.

===Elementary school teaching===
If your Moodle site will serve kids, consider [https://docs.moodle.org/31/en/Language_packs#Can_I_make_a_language_pack_for_kids.3F making a language pack for kids].

===Plugins for K-12 teaching===
For [https://en.wikipedia.org/wiki/K%E2%80%9312 K-12] teaching and learning environments, please consider translating the plugins that are included in the [https://moodle.com/cloud/school/?utm_source=Sendy&utm_medium=Email&utm_campaign=Newsletter_July2016 Moodle for School at MoodleCloud]:
* [https://moodle.org/plugins/mod_attendance Attendance]
* [http://bigbluebutton.org/ BigBlueButton]
* [https://moodle.org/plugins/mod_checklist Checklist]
* [https://moodle.org/plugins/atto_chemistry Chemistry editor]
* [https://moodle.org/plugins/mod_choicegroup Group choice]
* [https://moodle.org/plugins/block_xp Level up!]
* [https://moodle.org/plugins/mod_quizgame Quizventure]
* [https://moodle.org/plugins/tinymce_wordcount Word count]

===Plugins for University teaching===
For universities, there is a [https://docs.moodle.org/31/en/Tertiary_education#Moodle_plugins_by.2Ffor_Universities list of plugins by/for Universities], and a [https://docs.moodle.org/31/en/Tertiary_education#Discipline-specific_plugins link to discipline-specific plugins], which might be worth translating.

==Non-translatable strings==
While AMOS does a great job for translating the Moodle core and most Moodle plugin language strings, some English language strings are not available for translation with AMOS.

===Plugins in the [https://moodle.org/plugins/browse.php?list=category&id=38 Other] category===
The plugins classified as '[https://moodle.org/plugins/browse.php?list=category&id=38 Other] ' (Utilities, Experimental or Incubating) are not translatable by AMOS (see [http://lang.moodle.org/mod/forum/discuss.php?d=3113 this forum thread]). You can use the [[:en:Language customization|language customization]] tool within your Moodle (production or local) server to produce the .php file containing the translated language strings for your language and email this file to the particular 'other' plugin maintainer, so that it can be included in the lang folder within the downloadable Zip file for the plugin.

===Plugins with coding errors===
Some plugins (of types different from 'Other') available for download in the [https://moodle.org/plugins/ Moodle plugins directory] may not have English language strings available for translation in [https://lang.moodle.org/ AMOS] because of [https://docs.moodle.org/dev/index.php?title=Plugin_contribution_checklist&redirect=no coding errors], that must be identified and fixed by the plugin maintainer, See [https://docs.moodle.org/dev/Plugin_contribution_checklist#Strings Plugin contribution checklist:Strings]:
* The plugin code must not rely on trailing and leading whitespace in strings.
* The string file must be considered as pure data file with the syntax $string['id'] = 'value';
* No other PHP syntax such as [http://php.net/manual/en/language.operators.string.php concatenation], [http://php.net/manual/en/language.types.string.php heredoc and nowdoc] is supported by the tools that AMOS use when processing the strings (even if it may work in Moodle itself).
* Use neither string concatenation operators nor other PHP logic inside string files. Those should really be considered as plain data files with simple $string['key'] = 'value'; syntax, nothing more.

===Plugins with hard-wired English language strings===
Sometimes you might have translated 100% of the strings available in AMOS for a given plugin, and you can still view the original English (non-translated) strings.
* Please check that you have purged your browser cache and the server cache, waited for one hour (for AMOS to update the language packs), and updated your language packs.
* If the problem persists, please write the plugin maintainer by clicking at the 'Bug tracker' link shown in the given plugin's page in the [https://moodle.org/plugins/index.php Moodle plugins database].
* If the plugin author has nested additional 'Lang' folders inside any subdirectories within the plugin folder structure, the English language strings in these nested Lang folder will not be available for AMOS, and they would seem to be hard-wired. Please contact the plugin author.
* Most Moodle plugin authors have been very fast at replacing the English hard-coded strings with strings variables that can now be translated in AMOS.
* If you suspect the problem is in a core plugin, you can post an issue in the [https://lang.moodle.org/mod/forum/view.php?id=5 AMOS translation forum].

===Log descriptions can not be translated===
* See [https://docs.moodle.org/dev/Translation_FAQ#Why_are_log_descriptions_displayed_in_English.3F why log descriptions are not translated].

===Items that must NOT be translated===
* See the [https://docs.moodle.org/dev/Translation_FAQ#Are_there_items_which_are_not_to_be_translated.3F Items that are not to be translated] in the [https://docs.moodle.org/dev/Translation_FAQ Translation FAQ]

==If translations are available in AMOS for some Moodle branches but not available for other branches==
Sometimes a plugin may have its English language strings available for translations for some Moodle branches (e.g. 2.0 to 2.4), but not for other branches (e.g. 2.5 to 2.7), even though the plugin itself is indeed available for download for all branches (2.0 to 2.7) in the Moodle plugins database.

Please see an example in [http://lang.moodle.org/mod/forum/discuss.php?d=3939 this post]. The cause is very likely a programming error (see 'Plugins with coding errors' above), that must be fixed by the plugin maintainer.

==What happens if a plugin ZIP file includes translation(s) inside the lang folder==
If a site has debugging on, there will be a warning message about 'Found language file' when the user installs the plugin, but the installation may proceed.

[[File:Found language file debugging message.jpg|400px]]

The Language strings inside a properly installed downloaded plugin will overwrite the strings translations of the language pack, but they can be overwritten by the strings defined with the Language customization.

===Strings priority===
When displaying text language strings, Moodle 2.x and 3.x will have the following priority:
# Strings defined by the [[:en:Language customization|language customization]] tool
# Strings defined in an installed child language pack (eg, the es_ve language pack)
# Strings defined in an installed parent language pack (eg, the es language pack)
# Strings enclosed inside the plugin_name/lang/xx/yy.php folder (where xx is a language code other than the en folder) from a downloaded and installed plugin ZIP file (eg, inside the /server/moodle/theme/adaptable/lang/es/theme_adaptable.php file)
# Original Australian English language strings shipped with the downloaded Moodle branch.
# Original Australian English language strings inside the /lang/en folder in the downloaded/updated plugin ZIP file

Note: See the [https://moodle.org/plugins/local_string_override local String override plugin] that makes it possible for plugins to override existing translations regardless if they're bundled with Moodle or they're originated from a community plugin.

==See also==

* [http://lang.moodle.org/mod/forum/discuss.php?d=2485 Contributed plugins are now automatically imported into AMOS] announcement explaining the mechanism
* [https://docs.moodle.org/dev/Translation_FAQ#Are_there_items_which_are_not_to_be_translated.3F Items that are not to be translated] in the [https://docs.moodle.org/dev/Translation_FAQ Translation FAQ]

[[Category:Plugins]]

Moodle 3.6 release notes

2018-12-02T10:57:32Z

Mina: /* Privacy API update */

[[Releases]] > {{FULLPAGENAME}}

Release date: Not yet released - scheduled for 03 December 2018

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

{{Note|If you are upgrading from a previous version, please see [[:en:Upgrading|Upgrading]] in the user docs. ''In particular, for sites using a custom theme or login form, from 3.6 onwards, the login form must include a new login token field. See [[Login token]] for details.}}

==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.1 or later
* 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. [[Moodle and PHP7|PHP 7.3.x support]] is being implemented (@ MDL-63420) and '''not ready for production''' with this release.
* 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.6:
* Internet Explorer 10 and below
* Safari 7 and below

==Major features==

===Dashboard and Course overview===
* MDL-63044 and MDL-63337 - New [https://docs.moodle.org/36/en/Course_overview Course overview] and [https://docs.moodle.org/36/en/Timeline_block Timeline block]
* MDL-63062 - New [https://docs.moodle.org/36/en/Recently_accessed_courses_block Recently accessed courses block]
* MDL-63063 - New [https://docs.moodle.org/36/en/Recently_accessed_items_blockRecently accessed items block]
* MDL-63457 - Option to hide courses in the course overview block
* MDL-63058 - Option to star/unstar courses in the course overview block
* MDL-63064 - New [https://docs.moodle.org/36/en/Starred_courses_block Starred courses block]
* MDL-63352 - Dashboard retains user preferences for view options
* MDL-63793 - Course overview block retains user preferences for the number of courses to show
* MDL-61161 - Grace period when displaying "In progress" courses in course overview block
* MDL-63040 - Removal of Dashboard page header

===GDPR and Privacy===
Note that some of these GDPR improvements have also been backported to Moodle 3.5.3, 3.4.6 and 3.3.9.

* MDL-63116 - Data requests bulk actions
* MDL-62309 - Option to make site policies required or optional
* MDL-61652 - Capabilities for controlling who can download SAR data
* MDL-62563 - Data deletion of existing deleted users
* MDL-63897 - Pre-processing stage removed from data requests process
* MDL-62558 - Data retention summary (read-only)
* MDL-63726 - Option to remove the "Data retention summary" link in the footer
* MDL-62491 - HTML data request export format
* MDL-63401 - User expiry improvements
* MDL-63619 - Data purpose and category inheritance improvements
* MDL-62560 - Different data retention strategies for different roles in a purpose
* MDL-62554 - Ability to configure data registry to use module type defaults
* MDL-63009 - Site mentioned in email notifications of data requests
* MDL-6074 - Option to hide your name in the [https://docs.moodle.org/36/en/Online_users_block online users block]

===Messaging===
* '''MDL-57272 and MDL-63280 - Group messaging'''
* MDL-63303 - New messaging UI with [https://docs.moodle.org/36/en/Messaging messaging drawer]
* MDL-63279 - Option to [https://docs.moodle.org/36/en/Messaging_settings disable site-wide messaging]
* MDL-63214 - Privacy setting for restricting who can message you
* MDL-63213 - Option to star messaging conversations
* MDL-63283 - Notifications not sent for group conversations
* MDL-63281 - Group members synchronised with messaging conversations members

===Assignment===
* MDL-27520 - Assignment feedback can include media or other files

===Quiz===
* MDL-62610 - Improved quiz statistics report usability for randomized questions
* MDL-62708 - Option to add ID numbers to questions and question categories
* MDL-63738 - Single questions can be exported from the question bank

===Workshop===
* MDL-60820 - Teachers can specify workshop submission types

===Repositories===
* MDL-58943 - Nextcloud integration, with a [https://docs.moodle.org/36/en/Nextcloud_repository Nextcloud repository] and [https://docs.moodle.org/36/en/OAuth_2_Nextcloud_service OAuth 2 Nextcloud service]

===Open Badges===
* MDL-58454 - Support for Open Badges v2.0

===Performance===
* MDL-54035 - Performance improvements to cache flags
* MDL-47962 - Glossary auto-linking filter performance improvements

===Usability improvements===
* MDL-51177 - atto_htmlplus implemented to improve Atto editor HTML indenting
* MDL-45170 - Copy and paste of images from one WYSIWYG window to another
* MDL-61388 - Forum actions announced by screen reader when completed
* MDL-62899 - Global search displays a relevant icon next to link in results
* MDL-46415 - SVG/high resolution emoticons
* MDL-58000 - Larger badge images are used

===Experimental===
* MDL-53566 - [https://docs.moodle.org/36/en/Context_freezing Context freezing] - setting read-only access for categories, courses, activities and their content

==Other highlights==

===Functional changes===
* MDL-17943 - 'Resend confirmation email' button on login page
* MDL-14274 - IF conditions in grade calculations
* MDL-37624 - Calendar entries location support
* MDL-36754 - Images are displayed in forum notification emails
* MDL-59259 - Course format options may be specified in upload courses CSV file
* MDL-41265 - Page resource option to show/hide "Last modified"
* MDL-61378 - Forum post HTML structure improvements
* MDL-59454 - Option to download the list of course participants
* MDL-60520 - Analytics models can use different machine learning backends
* MDL-61573 - User menu: customusermenuitems map Font Awesome icons for non pix/t folders
* MDL-62320 - JSON added to the default MIME types list
* MDL-63431 - Atto media plugin title global attribute support
* MDL-60435 - Shibboleth authentication identity providers
* MDL-59169 - Grader report saves after edit with multiple tabs
* MDL-62960 - Drag and drop of course events respects the course start date

===Security issues===
* [https://moodle.org/mod/forum/discuss.php?d=378731 MSA-18-0020] Login CSRF vulnerability in login form. Note that this fix has previously been disclosed following the release of Moodle 3.5.3, 3.4.6, 3.3.9 and 3.1.15.

===For administrators===
* MDL-62334 - 'Add a new course' link in Site administration
* MDL-63253 - Admin search results provide location of the found matching page
* MDL-63772 - Capability to control use of Atto Record RTC
* MDL-63708 - New blocks supported by the mobile app can be disabled
* MDL-52953 - Legacy log store deprecation
* MDL-59429 - Log changes to site administrators
* MDL-62651 - adhoc task runner
* MDL-62777 - Site upgrades via CLI display new default settings
* MDL-63603 - Indian Rupee added to [https://docs.moodle.org/36/en/PayPal_enrolment PayPal enrolment] currencies

==For developers==
* MDL-55188 - Old Events API final deprecation
* MDL-54741 - Phase 2 of deprecation of functions in lib/deprecatedlib.php
* MDL-51803 - Reusable element for drag and drop sortable table or list
* MDL-63329 - memcache session handler removal
* MDL-63658 - New Favourites subsystem
* MDL-63729 - Badges web services return new fields and data added by the Open Badges v2.0 specification
* MDL-50812 - core_useragent::get_browser_version_classes distinguishes between different browsers

===Privacy API update===

In addition to existing requirements, any plugin which implements the plugin provider interface must also implement the <tt>\core_privacy\local\request\core_userlist_provider</tt> interface. Two new methods need to be implemented:

* [[Privacy API#Retrieving_the_users_in_a_context|get_users_in_context()]]
* [[Privacy API#Delete_personal_information_for_several_users_in_a_specific_context|delete_data_for_users()]]

However, the two above methods are not required for plugins that [[Privacy_API#Plugins_which_do_not_store_personal_data|implement the <tt>null_provider</tt>]] only (i.e. which do not store personal data).

Note that these changes are also required for latest Moodle 3.4.6 and 3.5.3 versions.

===Behat scenario files===

* MDL-57281 - The behat step <code>I navigate to "ITEM" node in "MAINNODE > PATH"</code> has been deprecated and throws an exception with details on how to replace it. The recommended replacement steps work in all recent Moodle versions. The updated Behat will pass with Moodle 3.4 too.

===Login token===

If your plugin provides an alternative login form (e.g. it is a theme replacing the default login form template / renderer), the login form must include a new login token field. For details of required changes, see [[Login token]]. Note that this also affects latest stable branches too.

===Component APIs upgrades===

Please refer to the upgrade.txt files in the relevant component directory for changes in this particular Moodle release.

* [https://git.in.moodle.com/moodle/moodle/blob/master/admin/tool/log/upgrade.txt admin/tool/log/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/admin/tool/upgrade.txt admin/tool/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/auth/shibboleth/upgrade.txt auth/shibboleth/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/auth/upgrade.txt auth/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/badges/upgrade.txt badges/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/blocks/upgrade.txt blocks/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/cache/upgrade.txt cache/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/calendar/upgrade.txt calendar/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/format/upgrade.txt course/format/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/upgrade.txt course/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/enrol/upgrade.txt enrol/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/filter/upgrade.txt filter/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/grade/grading/form/upgrade.txt grade/grading/form/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/grade/report/upgrade.txt grade/report/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/grade/upgrade.txt grade/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/upgrade.txt lib/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/media/upgrade.txt media/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/message/upgrade.txt message/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/assign/upgrade.txt mod/assign/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/feedback/upgrade.txt mod/feedback/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/forum/upgrade.txt mod/forum/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/quiz/upgrade.txt mod/quiz/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/scorm/report/basic/upgrade.txt mod/scorm/report/basic/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/scorm/upgrade.txt mod/scorm/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/upgrade.txt mod/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/workshop/upgrade.txt mod/workshop/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/question/format/upgrade.txt question/format/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/report/upgrade.txt report/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/tag/upgrade.txt tag/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/theme/upgrade.txt theme/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/user/upgrade.txt user/upgrade.txt]

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

[[Category:Release notes]]
[[Category:Moodle 3.6]]

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

Moodle 3.3 release notes

2017-12-21T13:58:51Z

Mina: /* Server requirements */ Clarification about utf8mb4 requirement, see https://moodle.org/mod/forum/discuss.php?d=363207

[[Releases]] > {{FULLPAGENAME}}

Release date: 15 May 2017

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

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

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

==Server requirements==

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

* Moodle upgrade: Moodle 2.7 or later (if upgrading from earlier versions, you must upgrade to 2.7.14 as a first step)
* PHP version: minimum PHP 5.6.5. ''Note: minimum PHP version has increased since Moodle 3.1''. PHP 7.0.x and 7.1.x are supported but have some [https://docs.moodle.org/dev/Moodle_and_PHP7#Can_I_use_PHP7_yet.3F engine limitations].
* PHP extensions '''openssl''' and '''fileinfo''' are now required in Moodle 3.3 (they were recommended in 3.2)
* If you use PostgreSQL the minimum supported version is now 9.3 (was 9.1 in Moodle 3.2)
* If you use MySQL or MariaDB, make sure your database supports full UTF-8 (utf8mb4) if you install a new instance of Moodle. CLI script may be used to convert to utf8mb4 if you're upgrading. You may choose to keep using 'utf8_*', but then a warning will show that the database isn't using full UTF-8 support and suggest moving to 'utf8mb4_unicode_ci'. See [[:en:MySQL full unicode support|MySQL full unicode support]] for details.

=== 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.3:
* Internet Explorer 10 and below
* Safari 7 and below

==Major features==

=== Highlights ===

* MDL-55611 - New [https://docs.moodle.org/33/en/Course_overview Course overview] dashboard block featuring timeline of events
* MDL-58220 - Make use of [https://docs.moodle.org/33/en/OAuth_2_services OAuth 2 services] to allow users to [https://docs.moodle.org/33/en/OAuth_2_authentication authenticate with Google G-Suite or Microsoft Office accounts] and manage files from associated drives
* MDL-39913 - New [https://docs.moodle.org/33/en/Assignment_settings Assignment setting] for restricting submission file types
* MDL-4782 - [https://docs.moodle.org/33/en/Stealth_activities "Stealth mode"] for resources/activities in a course - not displayed on the course page but available for students
* MDL-40759 - New Font Awesome icon font for all icons in Moodle

=== For teachers ===

* MDL-58138 - [https://docs.moodle.org/33/en/Activity_completion_settings Activity completion settings] for setting activity completion defaults and bulk editing of completion requirements
* MDL-48771 - [https://docs.moodle.org/33/en/Building_Quiz Quiz activity]: Option to delete multiple questions
* MDL-53814 - Quiz activity: Question type icons are displayed in the quiz manual grading overview
* MDL-55459 - [https://docs.moodle.org/33/en/Assignment_settings Assignment activity]: Annotated PDF comments are collapsible
* MDL-23919 - [https://docs.moodle.org/33/en/Database_activity_settings Database activity]: The setting "Required entries" is now an activity completion condition
* MDL-57769 - Topic and weeks course formats: After a course is created, sections can be added and removed only from the course page (it is no longer possible to have "orphaned" activities)
* MDL-46929, MDL-57456, MDL-57457 - [https://docs.moodle.org/33/en/Using_Forum Forum posts], [https://docs.moodle.org/33/en/Using_Glossary glossary entries] and [https://docs.moodle.org/33/en/Book_settings book chapters] may be tagged
* MDL-56251 - For courses in weekly format, a new [https://docs.moodle.org/33/en/Course_settings course setting] allows for the course end date to be calculated automatically
* MDL-47354 - Allow the page size in the Single view report to be configurable

=== Backup and restore ===

* MDL-34859 - Add site defaults for all restore settings, improve UI around "Overwrite course configuration" select
* MDL-40838 - Allow to restore non-default enrollment methods without restoring users
* MDL-57769 - When restoring/importing big courses in Weeks and Topics formats into small existing courses ajust the number of sections automatically

=== For administrators ===

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

* MDL-46375 - Support for storing files not on the local drive (there are no open-source solutions at the moment, developer's help is required to implement custom cloud storage)
* MDL-55528, MDL-58280 - New [https://docs.moodle.org/33/en/Document_converters document converter] plugin type allows alternatives to unoconv, such as the [https://docs.moodle.org/33/en/Google_Drive_converter Google Drive converter]
* MDL-55980 - Run individual scheduled tasks from web interface
* MDL-57896 - CLI wrapper for get_config() and set_config() methods
* MDL-57789 - Use Cache-Control: immutable when serving files
* MDL-37765 - New capability to bypass access restrictions, separated from capability to view hidden activities
* MDL-57913 - Convert external database authentication synchronisation to scheduled task

==== Plugins removal and deprecation ====

* The repository Skydrive is deprecated; please migrate to the newer [https://docs.moodle.org/33/en/OneDrive_repository OneDrive repository]
* The Dashboard block Course overview is replaced with a new block [https://docs.moodle.org/33/en/Course_overview Course overview] which is a different plugin. If you want to use the old block, you need to download and install it from https://moodle.org/plugins/block_course_overview

=== Mobile app support ===

* MDL-57410 - Allow admins to add new external links to pages in the main menu of the Mobile app
* MDL-57408 - Add new settings for allowing renaming strings in the Mobile app
* MDL-49423 - Add new settings for disabling Mobile app functionalities
* MDL-57759 - Allow offline attempts via the Mobile app in the lesson module
* MDL-57162 - Support Native App install banners for Android as well as iOS for the mobile app

=== Other improvements ===

* MDL-33483 - Google Docs repository: Save Doc files in different formats to RTF
* MDL-42266 - Improve the list of maximum file size options for file uploads
* MDL-51853 - Calendar subscriptions from imported files should be editable
* MDL-41729 - Add ability to change passwords for users using Shibboleth
* MDL-57572, MDL-57570, MDL-57355 - Redis and static caches performance improvements if igbinary library is installed
* MDL-56808 - SCORM module: Performance improvements when running SCORM 1.2 packages
* MDL-57686 - Add support for PDO databases in external database authentication
* MDL-57638 - RSS Block: RSS feeds are more heavily cached and correctly respect skip values

===For developers===

* MDL-55528 - New plugin type 'fileconverter' for file conversions, unoconv is now a plugin that can be replaced with scalable commercial solutions (see [[File Converters]])
* MDL-40759 - Font Awesome icon font is used for all icons in Moodle (see [[Moodle_icons#Font_awesome_icons|Moodle icons]])
* MDL-46375 - Support for storing files not on the local drive is implemented by allowing to override functionality of file_storage and stored_file classes (see [[File System API]])
* MDL-12689 - Convert all authentication plugins to use settings.php (see [https://github.com/moodle/moodle/blob/master/auth/upgrade.txt upgrade.txt])
* MDL-53978 - Add extra plugin callbacks for every major stage of page render (see [https://github.com/moodle/moodle/commit/5ebd1fb9768969956c9131df4274f9cdff7f0134 commit])
* MDL-58138 - Course modules may provide additional callbacks to participate in bulk editing of activities completion rules in a course
* MDL-58220 - Better office integration
* MDL-45584 - Multiple caches can be instantiated with the same definition but with different identifiers
* MDL-57769 - Course formats: Attribute 'numsections' was removed from topics and weeks, other course formats may want to implement similar changes
* MDL-55956 - Priority field for the calendar events allowing to specify the priority of overrides
* MDL-58566 - New methods for retrieving calendar events
* MDL-55941 - New element to select first name of first/last names is implemented in tablelib or can be used by developers elsewhere ([https://github.com/moodle/moodle/blob/master/lib/templates/initials_bar.mustache template])
* MDL-56519 - Lint behat .feature files
* MDL-57273 - New classes (core\persistent, core\form\persistent, core\external\exporter, \core\external\persistent_exporter) used to represent a data-model and export that data in a standard format for webservices (previously was used in competencies) (see [[Persistent form]], [[Persistent]], [[Exporter]])
* MDL-57490 - Removed several legacy JS functions from javascript-static.js
* MDL-57690 - mcore YUI rollup is no longer included on every single Moodle page (see [[https://moodle.org/mod/forum/discuss.php?d=346520 forum post]])

==== 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.2 to Moodle 3.3 (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/admin/upgrade.txt admin/upgrade.txt] changes to administration-related functions
* [https://raw.githubusercontent.com/moodle/moodle/master/cache/upgrade.txt cache/upgrade.txt] changes to Cache API
* [https://raw.githubusercontent.com/moodle/moodle/master/calendar/upgrade.txt calendar/upgrade.txt] changes to Calendar API
* [https://raw.githubusercontent.com/moodle/moodle/master/competency/upgrade.txt competency/upgrade.txt] changes to Competency API
* [https://raw.githubusercontent.com/moodle/moodle/master/course/upgrade.txt course/upgrade.txt] changes to course-related functions

For the next releases we are thinking about improving the format of upgrade.txt notes, please have your say on policy issue MDL-58879

'''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.2 and 3.3:
* [https://raw.githubusercontent.com/moodle/moodle/master/auth/upgrade.txt auth/upgrade.txt] Authentication plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/blocks/upgrade.txt blocks/upgrade.txt] Block plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/course/format/upgrade.txt course/format/upgrade.txt] Course format plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/enrol/upgrade.txt enrol/upgrade.txt] Enrolment method plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/media/upgrade.txt media/upgrade.txt] Media player plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/mod/upgrade.txt mod/upgrade.txt] Activity module plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/question/type/upgrade.txt question/type/upgrade.txt] Question types 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

'''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.2 and 3.3:

Due to changes in Authentication plugins settings all standard auth plugins were updated: [https://raw.githubusercontent.com/moodle/moodle/master/auth/cas/upgrade.txt auth_cas], [https://raw.githubusercontent.com/moodle/moodle/master/auth/db/upgrade.txt auth_db], [https://raw.githubusercontent.com/moodle/moodle/master/auth/email/upgrade.txt auth_email], [https://raw.githubusercontent.com/moodle/moodle/master/auth/fc/upgrade.txt auth_fc], [https://raw.githubusercontent.com/moodle/moodle/master/auth/imap/upgrade.txt auth_imap], [https://raw.githubusercontent.com/moodle/moodle/master/auth/ldap/upgrade.txt auth_ldap], [https://raw.githubusercontent.com/moodle/moodle/master/auth/manual/upgrade.txt auth_manual], [https://raw.githubusercontent.com/moodle/moodle/master/auth/mnet/upgrade.txt auth_mnet], [https://raw.githubusercontent.com/moodle/moodle/master/auth/nntp/upgrade.txt auth_nntp], [https://raw.githubusercontent.com/moodle/moodle/master/auth/none/upgrade.txt auth_none], [https://raw.githubusercontent.com/moodle/moodle/master/auth/pam/upgrade.txt auth_pam], [https://raw.githubusercontent.com/moodle/moodle/master/auth/pop3/upgrade.txt auth_pop3], [https://raw.githubusercontent.com/moodle/moodle/master/auth/shibboleth/upgrade.txt auth_shibboleth]

Other standard plugins that were updated in 3.3: [https://raw.githubusercontent.com/moodle/moodle/master/admin/tool/lp/upgrade.txt tool_lp], [https://raw.githubusercontent.com/moodle/moodle/master/admin/tool/mobile/upgrade.txt tool_mobile], [https://raw.githubusercontent.com/moodle/moodle/master/enrol/ldap/upgrade.txt enrol_ldap], [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/feedback/upgrade.txt mod_feedback], [https://raw.githubusercontent.com/moodle/moodle/master/mod/forum/upgrade.txt mod_forum], [https://raw.githubusercontent.com/moodle/moodle/master/mod/lesson/upgrade.txt mod_lesson]

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

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

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

[[Category:Release notes]]
[[Category:Moodle 3.3]]

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

Translating plugins

2017-07-20T17:26:20Z

Mina: /* Strings priority */ Priority corrected (see source code, function load_component_strings)

{{Translation}}
==Looking for translated plugins in the Moodle plugins database==

* Almost all contributed plugins published in Moodle Plugins directory have been imported into [http://lang.moodle.org/ AMOS] and are ready to be translated.
* When a user is looking at the [https://moodle.org/plugins/ Moodle plugins database], in ' Description tab > Useful links section' there is a link to 'Contribute translation for (your preferred language)' that points to [http://lang.moodle.org/ AMOS].
* Have a look at an example for the very popular [https://moodle.org/plugins/view.php?plugin=mod_hotpot HotPot] plugin:

[[File:Link to Plugin translations in Moodle plugins database.png|300px]]

* You can click on the 'Contribute translation for (your preferred language)' link.
* '''CURRENTLY:''' If you do not have an AMOS account, you would have to 'Create a new account' by using the appropriate link.
* If you have a translator account in AMOS, you can use AMOS to contribute the translation.
* If you select all the language packs (except English fixes) and write 'pluginname' in the box for 'String identifier', AMOS will display the name of the plugin in all available translations.
* Make sure that you have selected the Moodle branch(es) that you are interested in (eg, 2.5 in the image below).

[[File:Plugins translations in AMOS.png|400px]]

* In the above example, there are a total of 123 different language packs registered in AMOS; 63 of these are missing a translation for HotPot, which means that there are 60 different language translations already available for the HotPot plugin, a fair number for this popular plugin :)
* When no translation is available for any/many language(s), the box named 'Translation' will be empty for those languages.
* If a plugin name has been translated, there is a fair chance (but no certainty) that this plugin has been (completely) translated into that language. You can change the settings in AMOS and check for yourself.

==Plugin translation priority==
* Please help Moodle users in other languages by translating your favourite plugins.
* Moodle has a continuously updated [https://moodle.org/plugins/report/index.php?report=favourites&p=0&l=50&s=favourited&d=DESC list of the most favourite plugins], which might be worth considering for translation :)
* You can find the plugins with the largest number of downloads in the last three months at [https://moodle.org/plugins/stats.php https://moodle.org/plugins/stats.php]. These are the plugins most likely to be most useful when translated to your language. It would probably be a good idea to translate them first.
* Moodle has a list of plugins that have received the [https://moodle.org/plugins/browse.php?list=award&id=1 Reviewers' choice award]. These are given by the plugins guardians and reviewers for particularly useful, well coded or otherwise interesting plugins. It would be very desirable/useful to have these translated.
* See the [https://moodle.org/mod/forum/discuss.php?d=325804 list of (year 2015) favorite plugins] by Gavin Henrick
* Special cases:
** All plugins with ''mobile'' in their name, and all [https://moodle.org/plugins/browse.php?list=set&id=62 server side plugins] to support the [https://docs.moodle.org/31/en/Moodle_Mobile Moodle mobile app]
** [https://moodle.org/plugins/local_moodlecloudsignup MoodleCloud strings] are used for accessing the [https://moodle.com/cloud/ MoodleCloud] free and paid hosting services.

===Elementary school teaching===
If your Moodle site will serve kids, consider [https://docs.moodle.org/31/en/Language_packs#Can_I_make_a_language_pack_for_kids.3F making a language pack for kids].

===Plugins for K-12 teaching===
For [https://en.wikipedia.org/wiki/K%E2%80%9312 K-12] teaching and learning environments, please consider translating the plugins that are included in the [https://moodle.com/cloud/school/?utm_source=Sendy&utm_medium=Email&utm_campaign=Newsletter_July2016 Moodle for School at MoodleCloud]:
* [https://moodle.org/plugins/mod_attendance Attendance]
* [http://bigbluebutton.org/ BigBlueButton]
* [https://moodle.org/plugins/mod_checklist Checklist]
* [https://moodle.org/plugins/atto_chemistry Chemistry editor]
* [https://moodle.org/plugins/mod_choicegroup Group choice]
* [https://moodle.org/plugins/block_xp Level up!]
* [https://moodle.org/plugins/mod_quizgame Quizventure]
* [https://moodle.org/plugins/tinymce_wordcount Word count]

===Plugins for University teaching===
For universities, there is a [https://docs.moodle.org/31/en/Tertiary_education#Moodle_plugins_by.2Ffor_Universities list of plugins by/for Universities], and a [https://docs.moodle.org/31/en/Tertiary_education#Discipline-specific_plugins link to discipline-specific plugins], which might be worth translating.

==Non-translatable strings==
While AMOS does a great job for translating the Moodle core and most Moodle plugin language strings, some English language strings are not available for translation with AMOS.

===Plugins in the [https://moodle.org/plugins/browse.php?list=category&id=38 Other] category===
The plugins classified as '[https://moodle.org/plugins/browse.php?list=category&id=38 Other] ' (Utilities, Experimental or Incubating) are not translatable by AMOS (see [http://lang.moodle.org/mod/forum/discuss.php?d=3113 this forum thread]). You can use the [[:en:Language customization|language customization]] tool within your Moodle (production or local) server to produce the .php file containing the translated language strings for your language and email this file to the particular 'other' plugin maintainer, so that it can be included in the lang folder within the downloadable Zip file for the plugin.

===Plugins with coding errors===
Some plugins (of types different from 'Other') available for download in the [https://moodle.org/plugins/ Moodle plugins directory] may not have English language strings available for translation in [https://lang.moodle.org/ AMOS] because of [https://docs.moodle.org/dev/index.php?title=Plugin_contribution_checklist&redirect=no coding errors], that must be identified and fixed by the plugin maintainer, See [https://docs.moodle.org/dev/Plugin_contribution_checklist#Strings Plugin contribution checklist:Strings]:
* The plugin code must not rely on trailing and leading whitespace in strings.
* The string file must be considered as pure data file with the syntax $string['id'] = 'value';
* No other PHP syntax such as [http://php.net/manual/en/language.operators.string.php concatenation], [http://php.net/manual/en/language.types.string.php heredoc and nowdoc] is supported by the tools that AMOS use when processing the strings (even if it may work in Moodle itself).
* Use neither string concatenation operators nor other PHP logic inside string files. Those should really be considered as plain data files with simple $string['key'] = 'value'; syntax, nothing more.

===Plugins with hard-wired English language strings===
Sometimes you might have translated 100% of the strings available in AMOS for a given plugin, and you can still view the original English (non-translated) strings.
* Please check that you have purged your browser cache and the server cache, waited for one hour (for AMOS to update the language packs), and updated your language packs.
* If the problem persists, please write the plugin maintainer by clicking at the 'Bug tracker' link shown in the given plugin's page in the [https://moodle.org/plugins/index.php Moodle plugins database].
* If the plugin author has nested additional 'Lang' folders inside any subdirectories within the plugin folder structure, the English language strings in these nested Lang folder will not be available for AMOS, and they would seem to be hard-wired. Please contact the plugin author.
* Most Moodle plugin authors have been very fast at replacing the English hard-coded strings with strings variables that can now be translated in AMOS.
* If you suspect the problem is in a core plugin, you can post an issue in the [https://lang.moodle.org/mod/forum/view.php?id=5 AMOS translation forum].

===Log descriptions can not be translated===
* See [https://docs.moodle.org/dev/Translation_FAQ#Why_are_log_descriptions_displayed_in_English.3F why log descriptions are not translated].

===Items that must NOT be translated===
* See the [https://docs.moodle.org/dev/Translation_FAQ#Are_there_items_which_are_not_to_be_translated.3F Items that are not to be translated] in the [https://docs.moodle.org/dev/Translation_FAQ Translation FAQ]

==If translations are available in AMOS for some Moodle branches but not available for other branches==
Sometimes a plugin may have its English language strings available for translations for some Moodle branches (e.g. 2.0 to 2.4), but not for other branches (e.g. 2.5 to 2.7), even though the plugin itself is indeed available for download for all branches (2.0 to 2.7) in the Moodle plugins database.

Please see an example in [http://lang.moodle.org/mod/forum/discuss.php?d=3939 this post]. The cause is very likely a programming error (see 'Plugins with coding errors' above), that must be fixed by the plugin maintainer.

==What happens if a plugin ZIP file includes translation(s) inside the lang folder==
If a site has debugging on, there will be a warning message about 'Found language file' when the user installs the plugin, but the installation may proceed.

[[File:Found language file debugging message.jpg|400px]]

The Language strings inside a properly installed downloaded plugin will overwrite the strings translations of the language pack, but they can be overwritten by the strings defined with the Language customization.

===Strings priority===
When displaying text language strings, Moodle 2.x and 3.x will have the following priority:
# Strings defined by the [[:en:Language customization|language customization]] tool
# Strings defined in an installed child language pack (eg, the es_ve language pack)
# Strings enclosed inside the plugin_name/lang/xx/yy.php folder (where xx is a language code other than the en folder) from a downloaded and installed plugin ZIP file (eg, inside the /server/moodle/theme/adaptable/lang/es/theme_adaptable.php file)
# Strings defined in an installed parent language pack (eg, the es language pack)
# Original Australian English language strings shipped with the downloaded Moodle branch.
# Original Australian English language strings inside the /lang/en folder in the downloaded/updated plugin ZIP file

Note: See the [https://moodle.org/plugins/local_string_override local String override plugin] that makes it possible for plugins to override existing translations regardless if they're bundled with Moodle or they're originated from a community plugin.

==See also==

* [http://lang.moodle.org/mod/forum/discuss.php?d=2485 Contributed plugins are now automatically imported into AMOS] announcement explaining the mechanism
* [https://docs.moodle.org/dev/Translation_FAQ#Are_there_items_which_are_not_to_be_translated.3F Items that are not to be translated] in the [https://docs.moodle.org/dev/Translation_FAQ Translation FAQ]

[[Category:Plugins]]

Accessibility

2016-12-13T08:53:56Z

Mina: /* Web standards, guidelines and legislation */

Websites built with '''accessibility''' in mind are flexible in meeting different user needs, preferences and situations. Though these methods can increase [[Usability|usability]] for everyone who uses the Web they are often legally required to be implemented in a specific effort to prevent discrimination against people with disabilities.

== Starting points ==

These are some readable introductions to accessibility that cover; what accessibility is, why it is important, as well as practical advice.
* [http://www.w3.org/WAI/intro/accessibility.php Web Accessibility Initiative's ''Introduction to Web Accessibility'']
* [http://diveintoaccessibility.info/ Mark Pilgrim's ''Dive into Accessibility'']
* [http://joeclark.org/book/ Joe Clark's ''Building Accessible Websites'' book]

== Moodle Accessibility Collaboration Group ==
To improve the accessibility/usability of this learning management system, we have established this collaboration group to work together with Moodle developers, administrators, IT professionals, and other interested entities and individuals. We welcome anyone who is interested in improving the accessibility of Moodle to join this group. You don’t need to be a technical guru or accessibility expert to join; however, it is expected that you are familiar with the basics of accessibility and are willing to dedicate a few hours each month to this collaboration effort.

Visit http://collaborate.athenpro.org/group/moodle to join the mailing list.

We meet in regional groups once a month to discuss accessibility priorities for each region. Regions meet at the following times:

* North America: We meet on the 1st Monday of each month at 10am USA Pacific Daylight Saving Time/5pm UTC. (Time zone converter: http://www.worldtimebuddy.com/)
* Europe: Looking for leadership and members
* Asia Pacific: Looking for leadership and members
* Latin America: Looking for leadership and members

To review past regional meetings or to see up coming meetings visit http://collaborate.athenpro.org/group/moodle/teleconferences/

== Moodle-related accessibility coding guidelines ==

; Use CSS, but still use headings, strong and emphasis
: It is generally a good idea to separate a document's content HTML from how it is presented using CSS. There are some tags that affect a document's presentation but also contribute to the structure and meaning of the content. These tags should remain in HTML. This includes heading tags <code><h1>, <h2>, <h3>...</code>, which are used to form the document's hierarchical structure, and <code><strong></code> and <code><em></code> tags, which are used to add meaning to sections of text.
; Avoid using background images for important information
: Users of non-visual browsers cannot see images. They can read the <code>alt</code> tags of normal images, but background images are not presented like normal images.
; Image <code>alt</code> and <code>title</code> attributes
* An <code>alt</code> attribute is required (even if empty) on all images.
* If a link is wrapping an <code><img></code>, the <code><img></code> does not need a <code>title</code> attribute if the link has one.
* The <code>alt</code> for an image and the <code>title</code> for its surrounding link should usually differ. An image <code>alt</code> attribute provides a text equivalent to an image, whereas a <code>title</code> attribute adds supplementary information about the purpose or action associated with an image link. Simply repeating the same text in <code>alt</code> and <code>title</code> attributes adds little and can be annoying for screen reader users.
; Links and buttons should be selectable and easily click-able
* An image used as an icon for a user to click should be large enough so that the user can click on it easily.
* Users should be able to navigate to all links and buttons using the keyboard.
* Generally we should avoid having two buttons/links that achieve the same action in the same area. This can be annoying and confusing for users of screen readers.
; Support dynamic interaction with [[ARIA]] attributes
: Events triggered by AJAX and JavaScript can be less obvious to users of non-visual browsers. [[ARIA]] attributes can assist users of such browsers to follow a dynamic change.
; Use labels with inputs
: Context can easily be lost without a visual presentation. Labels are needed on all input input elements (except button) to describe their purpose in a form. Labels should be unique on a page. Repeated elements should have a unique label that identifies the element within its context.
; Use appropriate page titles
: A page title is a starting point for a screen reader. Page titles should be unique and should make sense for the page. Avoid generic page titles.
; All pages should be navigable using just a keyboard
: It should be possible navigate to all points on a page just using a keyboard. Important events triggered by a mouse event should be able to be triggered when the item receives focus through keyboard navigation.
; Avoid using colour alone to express meaning
: Colour-blind users need additional information to gain meaning if colour is used as the emphasising feature. Also keep in mind that colours can have differing significance in different cultures, so colours should be configurable either through settings or language files.
; Use sufficient color contrast when adding color to text. See Tracker ticket MDL 522391: https://tracker.moodle.org/browse/MDL-52391.
; Role for button-type links
: If a link acts as a button (not forwarding to another page, which is often the case when combined with Javascript), it should declare the ''role'' attribute ''button''. Also, as a button is usually triggered by the Space bar, the Javascript should add proper event listeners on the link to accept this key. Read more at [https://developer.mozilla.org/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role Mozilla Developer Network]

== Web standards, guidelines and legislation ==

=== International ===

* [http://www.w3.org/WAI/ Web Accessibility Initiative]
** [http://www.w3.org/WAI/intro/wcag.php Web Content Accessibility Guidelines (WCAG)]
** [http://www.w3.org/WAI/intro/wcag20 Web Content Accessibility Guidelines 2.0 (draft)]
*** An article on the [http://www.alistapart.com/articles/tohellwithwcag2 problems with WCAG2] from A List Apart
** [http://www.w3.org/TR/WCAG20-TECHS/client-side-script.html Client-side scripting guidelines]

* [http://www.w3.org/WAI/intro/aria.php W3C ARIA]

* [http://webaim.org/techniques/forms/controls WebAIM Form Accessibility guidelines]
* [http://webaim.org/techniques/aria/ WebAIM ARIA guidelines]

=== USA ===
* [http://www.section508.gov/ Section 508]

=== UK ===
* [http://www.legislation.gov.uk/ukpga/2010/15/contents Equality Act 2010], in particular:
** [http://www.legislation.gov.uk/ukpga/2010/15/section/20 Section 20 - Duty to make adjustments]
** [http://www.legislation.gov.uk/ukpga/2010/15/section/29 Section 29 - Provision of services, etc.]
** [http://www.legislation.gov.uk/ukpga/2010/15/schedule/25 Schedule 25 - Information society services].
: See also the [http://www.equalityhumanrights.com/uploaded_files/EqualityAct/servicescode.pdf Equality Act 2010 Statutory Code of Practice] (PDF) for Services, public functions and associations.
* [http://www.equalityhumanrights.com/advice-and-guidance/public-sector-equality-duty/ Public sector equality duty] created by the Equality Act 2010.
* [http://www.parliament.the-stationery-office.co.uk/pa/ld200001/ldbills/003/2001003.htm SENDA - Special Educational Needs and Disability Act/Bill]
* [http://www.opsi.gov.uk/acts/acts1995/1995050.htm Disability Discrimination Act 1995] (now merged ino the Equality Act 2010).
* [https://www.access8878.co.uk/getting-started-with-bs-8878/16-steps.aspx BS 8878:2010 – 16 Steps for an accessible web product]

=== Germany ===
* [http://www.einfach-fuer-alle.de/artikel/bitv/ Barrierefreie Informationstechnik-Verordnung - BITV]

=== France ===
* [https://references.modernisation.gouv.fr/rgaa-accessibilite/ Référentiel Général d’Accessibilité des Administrations - RGAA]

===European Union===
* [https://ec.europa.eu/digital-agenda/en/news/proposal-directive-european-parliament-and-council-accessibility-public-sector-bodies-websites Proposal for a Directive of the European Parliament and of the Council] on the accessibility of public sector bodies' websites.

== Tools ==

=== Firefox extensions ===
* [http://firefox.cita.uiuc.edu/ Firefox Accessibility Extension] by the Illinois Center for Information Technology and Web Accessibility (iCITA)
* [[Web developer extension]] for [[Firefox]]
* [[Blank_Your_Monitor_and_Easy_Reading_extension_for_Firefox|Blank Your Monitor and Easy Reading Extension]] for Firefox
* [http://www.deque.com/products/worldspace-fireeyes/download-worldspace-fireeyes|FireEye plugin for Firebug]
* [https://addons.mozilla.org/en-us/firefox/addon/wcag-contrast-checker|Color contrast plugin for Firefox]

=== Chrome extension ===
* [https://chrome.google.com/webstore/detail/color-contrast-analyzer/dagdlcijhfbmgkjokkjicnnfimlebcll Color Contrast Analyzer]
* [https://chrome.google.com/webstore/detail/high-contrast/djcfdncoelnlbldjfhinnjlhdjlikmph High contrast]
* [https://chrome.google.com/webstore/detail/chromelens/idikgljglpfilbhaboonnpnnincjhjkd/related ChromeLens]
* [https://chrome.google.com/webstore/detail/see/dkihcccbkkakkbpikjmpnbamkgbjfdcn SEE]
* [https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb Accessibility developer tools]

=== Accessibility validation tools ===
* [https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb?hl=en Chrome Accessibility Developer Tooks]
* [[W3C validation]] (for [[HTML in Moodle]], [[CSS]] and [[RSS]])
* [http://wave.webaim.org/ Web accessibility evaluation tool]
* [http://cynthiasays.com/ Cynthia Says accessibility checker]
* [https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd AXE]
* [https://chrome.google.com/webstore/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh WAVE]

=== Screen readers ===
* [http://www.standards-schmandards.com/projects/fangs/ Fangs – the screen reader emulator] for Firefox
* [http://www.nvda-project.org/ NVDA NonVisual Desktop Access] - open source screen reader for Windows
* [http://webaim.org/projects/screenreadersurvey4// WebAIM Screen reader survey] (Predominance of tools, browsers, OSs used by accessibility users)
* [http://www.chromevox.com/index.html ChromeVox] - Available in several languages for Linux, Windows and Mac OS, only on Chrome browser. (Android mobile users can use [https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback TalkBack])

See also this [http://www.w3.org/WAI/ER/tools/complete long list of accessibility tools].

See a [http://www.youtube.com/playlist?list=PLmQqs2jGU8Pr7e-3Fz2PoN6AabEkEBRYX live demonstration of a number of accessibility tools].

== Resources ==

* [http://webstandards.org/action/atf/manifesto/ Web Standards.org's ''Accessibility Task Force Manifesto'']
* [http://alistapart.com/topics/userscience/accessibility/ Accessibility articles from ''A List Apart'']
* [http://diveintomark.org/archives/2003/08/29/semantics Mark Pilgrim's ''Won’t somebody please think of the gerbils?'']
: [http://diveintoaccessibility.org/ Dive Into Accessibility] by Mark Pilgrim
* [http://joeclark.org/access/webaccess/ Joe Clark's writings on accessibility]
: [http://joeclark.org/book/ Building Accessible Websites] by Joe Clark (online version)
* [http://en.wikipedia.org/wiki/Web_accessibility Wikipedia article on ''Web Accessibility'']
* [http://juicystudio.com/article/validity-accessibility.php ''Validity and Accessibility'']
* [http://www.edtec.unsw.edu.au/inter/support/accessibility/access_vids.cfm Videos showing as student accessing another Learning Management System via Screen Reader software]

== See also ==

* [[:en:Accessibility|Accessibility statement]] - in current Moodle versions
* [[Semantic HTML]]
* [[Moodle Accessibility Specification]]
* See [[Usability FAQ]] for the related concept of usability.
* http://moodle.org/mod/forum/discuss.php?d=127807#p559951 (Old, 2009, might not be relevant any more)
* The [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] provides some extensive information and discussion on accessibility.
* [http://www.easy.pro.br/ EASY: Interface Between The Virtual Environment Moodle Learning and People with Visual Impairments]
* [http://www.bbc.co.uk/blogs/bbcinternet/2008/03/homepage_accessibilty.html BBC blog post on how their Web 2.0 homepage was made accessible]
* [http://www.bbc.co.uk/accessibility/ BBC Accessibility Help]
* [http://tracker.moodle.org/browse/MDL-7396 Accessibility Compliance in Moodle 1.8]
* [http://tracker.moodle.org/browse/MDL-7860 Compliance with Italian Legislation on Accessibility]
* [https://tracker.moodle.org/issues/?jql=project%20%3D%20MDL%20AND%20status%20%3D%20Open%20AND%20component%20%3D%20Accessibility%20ORDER%20BY%20affectedVersion%20DESC Open accessibility issues on the Tracker]

[[Category:Coding guidelines|Accessibility]]
[[Category:Accessibility]]

[[es:dev/Accesibilidad]]
[[fr:Accessibilité]]

Languages subsystem improvements 2.0

2009-12-09T08:02:23Z

Mina: /* Translation tool as an activity module */

{{Work in progress}}
{{Infobox Project
|name = Languages subsystem improvements
|state = Research and planning
|tracker = MDL-18797 MDL-15252
|discussion = [http://moodle.org/mod/forum/discuss.php?d=118707]
|assignee = [[User:David Mudrak|David Mudrak]]
}}
{{Moodle 2.0}}

This is an initial proposal of changes to the language strings processing in Moodle.

== Current issues ==

; String files are not branched : We must keep all strings from all branches in place for backwards compatibility and we are unable to easily clean up language packs. Some say the branching and merging is too big toast for our translators.
; Plural forms, gender forms and other grammar : We are unable to handle plurals at all. For example, handling [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html plural forms in gettext] is traditional, well tested and robust way (see MDL-4790). MDL-12433 by Sam Marshal shows alternative approach based on logical expressions.
; Strings can't be modified : It is difficult to notify translators that some string was modified (expanded, fixed, changed) - as in [http://git.moodle.org/gw?p=moodle.git;a=commit;h=d033b1288713625a733ce5fcbce5e7b5a1f6d5d1 this case], for example. The current work around it the policy of adding another string with the same suffixed name (like 'license2'). Would be nice if such strings were tagged/highlighted in the translation UI.
; We do not use standard formats : Translators can't use specialized tools for translation (PO/gettext editors, community translation portals). Also, I am not aware of any benchmarking showing the performance differences between out native $string[] format compared to, for example, standard .po format.
; More syntax checks are required : So the translators do not brake Moodle functionality (see MDL-12433)
; Language packs are PHP code, but stored in moodledata: This increases the severity of some security exploits. It means that any exploit that lets you write files to an arbitrary location in moodledata suddenly lets you execute arbitrary PHP code on the server. On the other hand, it would be nice to be able to allow complex logic when evaluating dynamic strings (ie such containing $a param/params).
; Right-to-left languages : There are problems reported in RTL languages when using online tools (including the our current one) which lead to putting placeholders like a$ and a$->lastname into the string definition.

== Goals ==

# Do not reinvent the wheel. Keep "do one thing and do it well" principle. Keep it simple and stupid. Have the translation process a simple as possible (translators are not geeks).
# Make simple things easy and hard things possible
#

== Key design questions ==

; What is the data structure for storing the master copies of the lang packs that translators work on : At the moment it is plain PHP array, editable via translation UI or directly. Petr proposes a change to keeping these strings in database, sort of syncable with some central repo. Whatever the format is, we must be able to store some metadata - the timestamp of the last modification, the author name, proposed alternatives, comments etc (see rosetta translation tool at launchpad for the example of possible metadata)
; What is the UI for translators, what are the processes of contributing and how the translations are redistributed to Moodle sites : Out translators should not be forced to use the only one possible tool. We should consider switching to a standardized common format (like PO or XLIFF) that is supported by a variety of advanced tools (equipped with translation memory, connected with dictionaries, i18n portals etc).
; What is the data structure Moodle uses at runtime : This is just a performance optimization (implementation detail), should be independent on the native format that humans work with so it could be modified anytime in the future. For example, see the system proposed by Tim based on calling class methods (inspired by Perl's Maketext).
; What is the format of a lang string, and how are placeholders substituted : This is the most important issue we have at the moment but as it is strongly tied together with the runtime format, it can be changed any time. On the other hand, both the UI and storage format must support it.

===Miscellaneous suggestions===

* Store downloaded lang packs in a new location $CFG->langpacks, which defaults to $CFG->datadir/lang. Paranoid admins can change this to a different location that is normally read-only for the web server, but which they will switch to read/write when then are performing an upgrade, doing lang editing, or installing a lang pack. The UI should therefore check whether $CFG->langpacks is writable before starting any of these operations, and explain the situation to admins if it is not.
* Use sort of template syntax so translators can replace static strings with a template. Syntax can be similar to what Smarty and other templating engines use. So far we should be fine with a basic set of {if} {else}, eq, gt, lt and some math oparators (including modulo). Such templates would be compiled into proper PHP code once during lang pack compilation. Strict rules shall apply so it should reduce the risk of executing malicious code.

== Use cases ==

# Developers add new strings to the core
# Translators translate untranslated core strings and publish their work
# Admins want to locally modify the language pack
# Contributors add new string to the contributed code
# Translators translate untranslated contrib strings and publish their work
# Admins don't want PHP code stored in moodledata.
# ...

== Research ==

This is the list of projects, resources and tools being explored

* [http://search.cpan.org/~ferreira/Locale-Maketext-1.13_82/lib/Locale/Maketext/TPJ13.pod Great CPAN article about software localization]. Plain string based lexicon is not enough. Strings can be translated by functions only. "A phrase is a function; a phrasebook is a bunch of functions."
* [http://en.wikipedia.org/wiki/XLIFF XLIFF] - XML Localization Interchange File Format
* [http://translate.sourceforge.net/wiki/virtaal/index Virtaal] - promising, we could have XLIFF <-> .php conversion
* [http://launchpad.net/+tour/translation Launchpad] - translation portal used by Ubuntu and many other projects. Would require BSD licensing, therefore IMO not suitable as we could not import our current GPL'ed translation. Seems to be pretty slow during the process.
* [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html Plural forms in gettext]
* [http://framework.zend.com/manual/en/zend.translate.html Zend_Translate reference guide]
* MDL-12433 - Sam Marshal's proposal
* MediaWiki approach: [http://www.mediawiki.org/wiki/Manual:$wgGrammarForms Grammar forms] and plurals: <code>{{plural:1|is|are}} {{plural:2|is|are}}</code> (Example of how mediawiki outputs the correct given pluralization form depending on the count. Plural transformations are used for languages like Russian based on "count mod 10").

== Functional proposals ==

=== Overall strings processing flow ===

(Follow the attached UML flow diagram) [[Image:languages20_overview1.png|thumb|right|UML: Overall string processing flow]]

* All string definitions are kept in a central repository in some storage format which supports branching. Officially maintained language packs are referred to as ''master'' in this proposal. Every language pack can have its ''parent'' defined. The English language pack can be seen as the greatest common parent of all language packs.
* During upgrade or on demand, the relevant branch of master language packs are fetched (downloaded) automatically from the central repository. Together with the selected language, all its parents, grandparent, great-grandparents, ... etc are downloaded, too.
* Administrators can keep local modifications (customizations) of any master pack. We call them ''local'' language packs.
* Immediately after upgrade (or again, on demand), the string definitions are merged from all available sources. The merge logic is so that the sources for any given string are evaluated in the order like: fr_ca_local, fr_ca, fr_local, fr, en_local, en. Strings are merged for the performance reasons so that the searching for the string to use (local, parent, master, English etc.) is done just once and we do not need to load all possible sources on runtime. After the merge, we have a single place to look for the string definition for every installed language.
* Together with the merge, strings are compiled into a runtime format that may be optimised in the future. Humans do not modify the compiled format. Strings must be re-merged and re-compiled after any update of master or local packs. During the compilation, syntax checks are performed.
* The runtime format we will start with will be very similar with the current one. Strings are defined as array elements indexed by the string identifier. The arrays are defined in separate files for every module. We can, however, modify this in the future. For example, we can divide string definitions into files not by the module name but by the real usage frequency. Strings that are used very often (like at every page) would go into common file which can be loaded during bootstrap. This would reduce memory usage and number of I/O operations.
* The only valid placeholder in runtime format is <code>{$a}</code> for strings and numbers and <code>{$a->foobar}</code> for objects.
* Around 90% of our strings do not contain any placeholder and they will be immediately returned by get_string().
* If the string contains one or more placeholders, they are replaced with their eval()-uated result. We can safely eval() the whole string definition because the string compiler makes sure that the placeholders are the only executable/evaluable code. All other malicious code and $variables are properly quoted/escaped/htmlentitled.
* If the string is defined as NULL, corresponding function defined in the language pack library is called, passing $a as parameter. So <code>get_string('foo', 'bar', $a);</code> would return the value returned by eg <code>lang_cs_bar_foo($a)</code> if the current language is Czech. Power translators may use such functions to properly handle plural forms and other grammar aspects.

=== Mental model of branching for translators ===

(Follow the attached scheme) [[Image:lang20branchingmentalmodel.png|thumb|right|Mental model of branching]]

It may not be trivial to understand the principle of ''branching'' and ''merging'' as they seem to be quite geeky tech terms. Maybe the following model based on layers can be more suitable for good translators. Basically, strings are seen as being part of a layer. For every Moodle release, a new layer is put on the top of all other layers. The get_string() at every release looks at its layer for the string definition. If the string is defined on that layer, the first underlying layer the string is defined at is used. So, for example:
* stringid01 was defined in Moodle 1.9 (it was part of the Moodle language pack before we did the big Moodle 2.0 cleanup). It remains the same for all following releases.
* stringid02 was defined in Moodle 1.9. Then it changed in Moodle 2.0 and then again in Moodle 2.3. In Moodle 2.1 and 2.2, the version defined in 2.0 is used.
* stringid03 was introduced in Moodle 2.0. There is no need to translate it for the previous releases because it does not exist there.
* stringid04 is similar to stringid02. It appeared sometimes/somewhere in Moodle 1.x (until Moodle 2.0, we did not branch), was changed in 2.1 and then again in 2.2
* stringid05 was dropped in Moodle 2.0 and is not part of the language pack any more. There is no need to translate it for Moodle 2.x
* stringid06 was introduced in Moodle 2.3
* stringid07 was dropped in Moodle 2.0 but then it reincarnated in Moodle 2.2 and is the part of the languages again since then (even its definition could change)
* stringid08 (you now should be able to explain yourself ... :-)

=== Translation tool as an activity module ===

* MDL-18797
* lives in contrib, translators and administrators wanting to customize the language pack install it
:: -- [[User:Nicolas Martignoni|Nicolas Martignoni]] 08:02, 9 December 2009 (UTC): IMHO translation tool have to live in core, not in contrib, as translators should have total confidence in its functionalities (contrib is frequently associated with "unstable" and/or "not maintained"). Moreover, such a tool has to be always up-to-date.
* various capabilities to propose (submit) alternative translations, to integrate proposals, rate them, export them, send to upstream etc.
* such activity can be used by individuals, translation teams, can handle community-based models etc.
* strings are saved in DB with all metadata, history etc.
* XLIFF used as exchange format with upstream
* CVS access replaced with a web service at a dedicated lang.moodle.org server

== Implementation proposals ==

[http://moodle.org/mod/forum/discuss.php?d=118707#p542197 Petr's proposal] to store strings in one central database and to disable direct commits.
: --[[User:David Mudrak|David Mudrak]] 22:43, 23 November 2009 (UTC): I disagree with the "no change meaning" rule. IMO if we have a system how to track changes and mainly how to inform translators that their translation is outdated, we can fix/update/extend English string as needed. Together with branching, this will lead to a nice "reduced" packs without redundancy. Also note we must find a way how to combine this approach with the grammar issues (plural forms etc) that will probably have to be solved as proper PHP functions/class methods...

=== File format translators work with ===

=== Translation tool a the process ===

See MDL-15252 (Cleanup of English language pack) and the discussion at http://moodle.org/mod/forum/discuss.php?d=118707 for Koen's proposition. Branching issue, the translation process and other aspects discussed there.

From Martin in Dev chat: ''if you want crazy ideas, how about get_string returns some special tags and those tags get converted to ajax on the GUI so that translators can translate directly in the main Moodle GUI?''

What a cool idea. Could be a special mode you have to turn on in the admin screens. Perhaps even if you turned this mode on, it would still only be active for people with certain roles, or perhaps when it was turned on, it would have to apply to all roles, so that you could edit strings for not-logged-in users. Anyway, when this mode was on, it would:

# Adds <span class="moodle-lang-string" id="lang_string|admin|langedit">Language editing</span> around each string on the page - to use one example.
# $PAGE->requires->js an extra JS file that adds an on-click handler to all such spans, so that when you click on it, it pops up the language editing UI in a YUI dialogue.

:: [[User:David Mudrak|David Mudrak]] 14:07, 23 November 2009 (UTC): the solution based on wrapping <span> around every string was already considered and dropped. It may badly break XHTML as the string itself may appear as a value of an HTML tag's attribute: <code><img title="<span class="moodle-lang-string" ...</code>. We are unable to say the scope where the string will appear.
:: David's contra-proposal: get_string() could track all strings used at the current page and the AJAX form to edit them all could be rendered before the footer(). Or 'Edit system text on this page' link would appear there.

=== Runtime file format===

* [[Languages:Tim's crazy proposal based on maketext]]

== See also ==
* [http://live.gnome.org/TranslationProject/GitHowTo How to use Git for GNOME translators]
* [http://translate.sourceforge.net/wiki/ Nice site with tools, localisation problems and alternatives...]

[[Category:Language]]

Languages:Tim's crazy proposal based on maketext

2009-11-23T12:07:50Z

Mina: /* Proposed runtime lang file syntax */ Typo

They say that the border between madness and genius is is very narrow. Here goes.

The best article I know about the problems of localising software is http://search.cpan.org/~ferreira/Locale-Maketext-1.13_82/lib/Locale/Maketext/TPJ13.pod. I particularly like the narrative in the first half. Also, I must warn you that I have not read much about localisation, so my endorsement may not mean much.

OK, so the key point it makes is that really, a language string like "There have been $a quiz attempts" is really a function (in the mathematical sense of a mapping, not necessarily as a programming language construct). Depending on $a, we want it to output
* There have been no quiz attempts
* There has been one quiz attempt
* There have been 42 quiz attempts

So the question is, why not make it a function in the programming language construct sense as well.

==Two representations==

Up to Moodle 1.9, the files Moodle used at runtime were exactly the same as the files that translators edited. That was convenient, but limited us to a human-readable and editable format. Also, it meant that Moodle had to do a lot of searching at runtime.

In Moodle 2.0 we are already proposing to split the representations, which lets us optimise the runtime format to be pretty much whatever we like, without making the format edited by translators impossible.

==Proposed runtime lang file syntax==

In <tt>moodledata/lang/</tt> there are subfolders like <tt>en/</tt> (note we lose the legacy <tt>_utf8</tt>) that contains files like <tt>mod_quiz.php</tt> or <tt>core_moodle.php</tt>, that is, using the new component naming convention.

Suppose we have a hypothetical plugin <tt>admin/report/dylan</tt> with its current lang file <tt>admin/report/dylan/lang/en_utf8/report_dylan.php</tt> that contains:
<code php>
<?php
$string['howmanyroads'] = 'How many roads must a man walk down?';
$string['roadsx'] = 'Roads: $a';
$string['xroadsfromytowns'] = '$a->numroads roads from at least $a->numcities different cities.';
// Can't really handle pluralisation in that last one in Moodle :-(
</code>

In my new proposal, <tt>moodledata/lang/en/report_dylan.php</tt> will contain:
<code php>
<?php
class strings_en_report_capability extends strings_base {
protected static $helper = lang_helper_en::get(); // Get singleton instance.
public function howmanyroads($a) { return 'How many roads must a man walk down?'; }
public function roadsx($a) { return self::$helper->quant($a, 'road'); }
public function xroadsfromytowns($a) {
return self::$helper->quant($a->numroads, 'road') . ' from at least ' .
self::$helper->quant($a-> numcities, 'different city', 'different cities') . '.';
}
}
</code>
(I manually line-wrapped that last example to make it readable. in reality, remember that this file is being automatically compiled from some more human-readiable source.)

Also note that <tt>moodledata/lang/fr/report_dylan.php</tt> will look like:
<code php>
<?php
include_once($CFG->langdir . '/en/report_dylan.php');
class strings_fr_report_capability extends strings_en_report_capability {
protected static $helper = lang_helper_fr::get(); // Get singleton instance.
public function howmanyroads() { return 'Combien de rue ...'; }
// etc.
}
</code>

And <tt>moodledata/lang/fr_ca/report_dylan.php</tt> is:

<code php>
<?php
include_once($CFG->langdir . '/fr/report_dylan.php');
class strings_fr_ca_report_capability extends strings_en_report_capability {
}
</code>

==Using that runtime format==

Then, <tt>string_manager()</tt> becomes:
<code php>
class string_manager {
protected $stringclasses = array();
public function get_string($identifier, $component = '', $a = null) {
$component = $this->fix_legacy_component_names($component);
$this->get_string_class(current_language(), $component)->$identifier($a);
}
protected function get_string_class($lang, $component) {
global $CFG;
if (!isset($this->stringclasses[$lang][$component])) {
$this->stringclasses[$lang][$component] =
$this->load_string_class($lang, $component)();
}
return $this->stringclasses[$lang][$component];
}
protected function load_string_class($lang, $component) {
$file = "$CFG->langdir/$lang/$component.php";
$class = "strings_{$lang}_{$component}";
if ($CFG->langediting && !$this->is_up_to_date($file)) {
compile_lang_strings($lang, $component);
}
if (!is_readable($file)) {
return new strings_base(); // See below.
}
include_once($file);
if (!class_exists()) {
throw new coding_exception($file . ' did not define the ' . $class .
'class. There must be a bug in compile_lang_strings.');
}
return new $class();
}
// A few other methods omitted.
}
</code>
Note that if you have a developer/translator flag on (<tt>$CFG->langediting</tt>) then <tt> is_up_to_date</tt> checks various file timestamps, so that lang files can automatically be recompiled as needed for those people, without hurting runtime performance for production sites.

As a final bit of magic, we have
<code php>
class strings_base {
public function __call($name, $arguments) {
return "[[$name]]";
}
}
</code>

Remember that the strings_en_report_capability inherited form this. This gives us our classing missing string fallback. Also:

<code php>
class lang_helper_en {
private static $inst = null;
public static get() {
if (!$inst) {
$inst = new lang_helper_en();
}
return $inst;
}
public function quant($number, $singular, $plural = '') {
if ($number = 1) {
return "$number $singular";
} else if ($plural) {
return "$number $plural";
} else {
return "$number {$singular}s";
}
}
// Other helper functions.
}
</code>

==Problems==

I think this gives us the fastest possible runtime performance (particularly when combined with a PHP accelerator. Of course, it leaves open the following problems:
* what string format do translators to edit? (I suggest we copy the maketext format.)
* can we write the <tt>compile_lang_strings</tt> function?

==See also==

* [[Languages]]

{{CategoryDeveloper}}
[[Category:Language]]

Languages subsystem improvements 2.0

2009-11-22T18:22:53Z

Mina: /* Current issues */

{{Infobox Project
|name = Languages subsystem improvements
|state = Research and planning
|tracker = n/a
|discussion = n/a
|assignee = [[User:David Mudrak|David Mudrak]]
}}
{{Moodle 2.0}}

This is an initial proposal of changes to the language strings processing in Moodle.

== Current issues ==

; String files are not branched : We must keep all strings from all branches in place for backwards compatibility and we are unable to easily clean up language packs. Some say the branching and merging is too big toast for our translators.
; Plural forms, gender forms and other grammar : We are unable to handle plurals at all. For example, handling [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html plural forms in gettext] is traditional, well tested and robust way (see MDL-4790). MDL-12433 by Sam Marshal shows alternative approach based on logical expressions.
; Strings can't be modified : It is difficult to notify translators that some string was modified (expanded, fixed, changed). The current work around it the policy of adding another string with the same suffixed name (like 'license2'). Would be nice if such strings were tagged/highlighted in the translation UI.
; We do not use standard formats : Translators can't use specialized tools for translation (PO/gettext editors, community translation portals). Also, I am not aware of any benchmarking showing the performance differences between out native $string[] format compared to, for example, standard .po format.
; More syntax checks are required : So the translators do not brake Moodle functionality (see MDL-12433)

== Goals ==

# Do not reinvent the wheel. Keep "do one thing and do it well" principle. Keep it simple and stupid.
# Make simple things easy and hard things possible
# ...

== Key design questions ==

; What is the data structure for storing the master copies of the lang packs that translators work on : At the moment it is plain PHP array, editable via translation UI or directly. Petr proposes a change to keeping these strings in database, sort of syncable with some central repo. Whatever the format is, we must be able to store some metadata - the timestamp of the last modification, the author name, proposed alternatives, comments etc (see rosetta translation tool at launchpad for the example of possible metadata)
; What is the UI for translators, what are the processes of contributing and how the translations are redistributed to Moodle sites : Out translators should not be forced to use the only one possible tool. We should consider switching to a standardized common format (like PO or XLIFF) that is supported by a variety of advanced tools (equipped with translation memory, connected with dictionaries, i18n portals etc).
; What is the data structure Moodle uses at runtime : This is just a performance optimization (implementation detail), should be independent on the native format that humans work with so it could be modified anytime in the future. For example, see the system proposed by Tim based on calling class methods (inspired by Perl's Maketext).
; What is the format of a lang string, and how are placeholders substituted : This is the most important issue we have at the moment but as it is strongly tied together with the runtime format, it can be changed any time. On the other hand, both the UI and storage format must support it.

== Use cases ==

# Developers add new strings to the core
# Translators translate untranslated core strings and publish their work
# Admins want to locally modify the language pack
# Contributors add new string to the contributed code
# Translators translate untranslated contrib strings and publish their work
# ...

== Research ==

This is the list of projects, resources and tools being explored

* [http://search.cpan.org/~ferreira/Locale-Maketext-1.13_82/lib/Locale/Maketext/TPJ13.pod Great CPAN article about software localization]. Plain string based lexicon is not enough. Strings can be translated by functions only. "A phrase is a function; a phrasebook is a bunch of functions."
* [http://en.wikipedia.org/wiki/XLIFF XLIFF] - XML Localization Interchange File Format
* [http://translate.sourceforge.net/wiki/virtaal/index Virtaal] - promising, we could have XLIFF <-> .php conversion
* [http://launchpad.net/+tour/translation Launchpad] - translation portal used by Ubuntu and many other projects. Would require BSD licensing, therefore IMO not suitable as we could not import our current GPL'ed translation. Seems to be pretty slow during the process.
* [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html Plural forms in gettext]
* [http://framework.zend.com/manual/en/zend.translate.html Zend_Translate reference guide]
* MDL-12433 - Sam Marshal's proposal
* MediaWiki approach: [http://www.mediawiki.org/wiki/Manual:$wgGrammarForms Grammar forms] and plurals: <code>{{plural:1|is|are}} {{plural:2|is|are}}</code> (Example of how mediawiki outputs the correct given pluralization form depending on the count. Plural transformations are used for languages like Russian based on "count mod 10").

== Proposals ==

* [[Languages:Tim's crazy proposal based on maketext]]

== See also ==
* [http://live.gnome.org/TranslationProject/GitHowTo How to use Git for GNOME translators]
* [http://translate.sourceforge.net/wiki/ Nice site with tools, localisation problems and alternatives...]

[[Category:Language]]

Finding your way into the Moodle code

2008-03-29T11:09:05Z

Mina: /* PHP for commplete novices */ Typo

This article is aimed at people totally new to Moodle development, who may, or may not, have previous programming experience. It is a few tips to help you get started with the mass of Moodle code.

Please feel free to add more tips here, but I think it is also good if we can keep this article quite short.

==Developer documentation==

If you have not already found it, the main source of developer documentation is [[Developer_documentation]].

==PHP for complete novices==

Moodle is written in [http://www.php.net PHP] - a relatively easy language to learn.

===How it works===
When your browser requests a webpage, you are asking for a file. The computer (server) you connect to at the other end of the internet normally sends back a file of [http://en.wikipedia.org/wiki/Html HTML] (which you need to get familiar with if you are not already) that your browser then converts into a webpage. HTML documents are static, meaning that they exist on the server in the same form as they are sent to you. PHP on the other hand is dynamic - the form it exists in on the server is different from what is ultimately sent to you, which may be different for different people. When a PHP file is requested, the server runs the instructions it contains and sends the output (HTML) to you in the normal way. PHP code can either be inserted into part of an HTML document, or can exist in files with nothing but PHP. You can recognise it by its start (<?php) and end (?>) tags

PHP almost always uses a database to store information. That way, the PHP forms a template, that gets filled with whatever information is appropriate to the user e.g. there is a space at the top right of this page for a username, but it is different for everyone.

In the following examples, the numbered line indicates what the intention of the developer is and the text in the box with the blue dashed outline is the code that would actually be written in the php file. Notice that the php lines always end with a ; symbol to indicate the end of a command.

The PHP code for the username box will say some thing like:

1. start a box by printing <div>
echo "<div>";
2. set the font colour to blue by printing <font color="#002bb8">
echo "<font color="#002bb8">";
3. get the username for user number x from the database
$username=fullname(123);
4. print that username
echo $username;
5. end font colour by printing </font>
echo "</font>";
6. end div by printing </div>
echo </div>

End result (HTML that will be sent to your browser):
<div>
<font color="#002bb8">
Joe Bloggs
</font>
</div>

===Variables===

In the above example, $username is a variable. It is effectively algebra, where a word of some sort (starting with a dollar sign) represents a piece of data, in this case the username returned by the database.

===Functions===

In the above example, fullname() is a function. This means a collection of commands (which in this case accesses the user table of the database and returns the name) that have been defined elsewhere, which can be run using a shorthand reference. This saves writing them out hundreds of times in different places. Functions are often written down in large library files, so that they can be used whenever they are needed.

===Including other files===

Moodle is a very complex program. Instead of just one page with a list of commands, it uses a great many files linked together using the [http://uk.php.net/include/ include] or [http://uk.php.net/manual/en/function.require-once.php require_once] commands. This means that when you request e.g. the front page, there will be commands such as the following:

require_once('config.php');

which means 'if its not been done already for this page request, go and get config.php and run all of its instructions before continuing'. In this way, a single Moodle webpage can sometimes include as many as 150 separate files on the server. This is how the library files are made available - you include the library and can then use any of the functions that the library contains e.g. fullname().

===Libraries and functions===

To make the username commands above into a function, we would write them like this:

function print_username_box($useridnumber) {
echo "<div>";
echo "<font color="#002bb8">";
$username=fullname($useridnumber);
echo $username;
echo "</font>";
echo </div>
}

Now, whenever the commands are needed, the developer simply writes
print_username_box(123);

==Finding a way in==

For finding where to start, you need to know that when you are looking at, for example, http://moodle.org/mod/forum/discuss.php?d=82799, then the code for that is in /mod/forum/discuss.php, and you just need to follow through what it does.

It calls functions in the main Moodle libraries, and the three most important are:

*lib/moodlelib.php - general stuff.
*lib/weblib.php - things to do with output of HTML
*lib/dmllib.php - things to do with getting data in and out of the database.

==Understanding what you find==

As you look at the code, it is often a good idea, to insert statements like
debugging('In function require_login');
which will print the message above if it gets far enough so you know the code has not stalled before there, or
print_object($course);
which will print out a variable, showing you what it contains.

Variable like $course are often objects with lots of fields. Seeing what they contain will help you understand what is going on. The first of these prints out whatever text you give it, and information about the sequence of function calls that the code took to get there. (It only works if you go to ''Administration > Server > [[Debugging]]'', and turn the debug level to ALL or DEVELOPER.)

==Tools can help==

Finally, it is helpful to have an editor that lets you jump around the code. For example, I like Eclipse, and if I hold down CTRL and click on the name of a function, it immediately jumps me to where that function if defined. Most good editors (including Emacs and vi/Vim) can do this. ([[Setting_up_Eclipse]])

==See also==

* First posted at http://moodle.org/mod/forum/discuss.php?d=82799#p366264
* [[Developer_documentation]]
* [[Overview]]
* [[ctags]]

Coding

2008-03-19T17:11:16Z

Mina: /* General rules */ Infos added about p() and s() functions. See MDL-13975

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include (require_once) the main config.php file.
# Any other include/require should use an absolute path beginning with $CFG->dirroot or $CFG->libdir, not relative includes, which [http://uk.php.net/manual/en/function.include.php sometimes behave strangely under PHP].
# Each file should check that the user is authenticated correctly, using require_login() and has_capability() or require_capability().
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string(). Never delete strings to ensure backwards compatibility of the language packs is maintained.
# Don't use p() and s() functions to print language strings. Those functions are not designed to print html with tags. Use echo() instead.
# All errors should be printed using print_error() to maximise translation and help for users (it automatically links to the docs wiki).
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Output_functions|output functions]].
# User actions should be logged using the [[Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].
# When generating a HTML link, always make it relative to the full site root, i.e. link to ''$CFG->wwwroot/mod/blonk/view.php?id=99'' rather than just ''view.php?id=99''. This means that your code will work if called by a script in another folder, among other things.

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, so that [http://php.net/types.string less memory is used].

$var = 'some text without any variables';
$var = 'with special characters like a new line '."\n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.

BAD: $b = $a;
GOOD: $b = clone($a);

If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.

==Database structures==

To help you create tables that meet these guidelines, we recommend you use the built in [[XMLDB_defining_an_XML_structure#The_XMLDB_editor|database definition (XMLDB) editor]].

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.
# '''Never''' make database changes in the STABLE branches. If we did, then users upgrading from one stable version to the next would have duplicate changes occurring, which may cause serious errors.
# When refering to integer variable in SQL queries, do not surround the value in quotes. For example, get_records_select('question', "category=$catid") is right. get_records_select('question', "category='$catid'") is wrong. It hides bugs where $catid is undefined. ([http://moodle.org/mod/forum/discuss.php?d=80629 This thread explains].)

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from.
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have [[Developer:Slashes|addslashes()]] applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.
# If you need to use shell_exec() (or any other shell invoking function), make sure you clean parameters first with escapeshellcmd()/escapeshellarg (otherwise, we open up for shell injection attacks).

[[Category:Coding]]

[[es:Manual de Estilo de Código]]
[[ja:コーディング]]
[[zh:代码指南]]
[[pl:Kodowanie]]

Talk:Language pack untranslated strings

2007-12-02T20:55:42Z

Mina:

Hi Koen,

Do you have a automated tool to get these stats?

--[[User:Nicolas Martignoni|Nicolas Martignoni]] 04:18, 30 November 2007 (CST)

:No, unfortunately not. I created it for the GHOP project - to get a view for students where there is work in the language packs to be done. --[[User:koen roggemans|koen roggemans]] 05:13, 30 November 2007 (CST)

:::Nicolas, congratulations on having zero untranslated strings in the French language pack - great work! :-) --[[User:Helen Foster|Helen Foster]] 06:19, 30 November 2007 (CST)

::::Thanks, Helen, the french team is doing his best for Moodle ;-) --[[User:Nicolas Martignoni|Nicolas Martignoni]] 14:55, 2 December 2007 (CST)

Talk:Language pack untranslated strings

2007-11-30T10:18:55Z

Mina:

Hi Koen,

Do you have a automated tool to get these stats?

--[[User:Nicolas Martignoni|Nicolas Martignoni]] 04:18, 30 November 2007 (CST)

Activity modules

2007-10-28T21:05:17Z

Mina: /* See also */

'''Activity modules''' reside in the 'mod' directory. Each module is in a separate subdirectory and consists of the following mandatory elements (plus extra scripts unique to each module):

* ''mod.html'' - a form to set up or update an instance of this module
* ''version.php'' - defines some meta-info and provides upgrading code
* ''icon.gif'' - a 16x16 icon for the module
* ''db/'' - SQL dumps of all the required db tables and data (for each database type)
* ''index.php'' - a page to list all instances in a course
* ''view.php'' - a page to view a particular instance
* ''lib.php'' - any/all functions defined by the module should be in here. If the modulename is called widget, then the required functions include:
:* widget_install() - will be called during the installation of the module
:* widget_add_instance() - code to add a new instance of widget
:* widget_update_instance() - code to update an existing instance
:* widget_delete_instance() - code to delete an instance
:* widget_user_outline() - given an instance, return a summary of a user's contribution
:* widget_user_complete() - given an instance, print details of a user's contribution
:* Other functions available but not required are:
:** widget_delete_course() - code to clean up anything that would be leftover after all instances are deleted
:** widget_process_options() - code to pre-process the form data from module settings
:** [[Implementing Reset course functionality in a module|widget_reset_course_form() and widget_delete_userdata()]] - used to implement [[Reset course]] feature.
:* To avoid possible conflict, any module functions should be named starting with widget_ and any constants you define should start with WIDGET_
* ''config.html'' - (optional) a form to set up or update global settings of this module
* ''lang/en_utf8/resource_widget.php'' - (optional) Lastly, each module will have some language files that contain strings for that module.

IMPORTANT: When creating a new module, the new name of the module must not contain numbers or other special characters!

You should also make sure that your activity module provides appropriate support for groups and metacourses.

==See also==

* Tracker issue [http://tracker.moodle.org/browse/CONTRIB-52 CONTRIB-52 Improvements to make NEWMODULE really useful] - including download link for new module template supporting roles, formslib etc. (unfinished)
* http://download.moodle.org/plugins16/mod/NEWMODULE.zip - new module template for versions of Moodle prior to 1.7. Please follow the README instructions inside the zip.
* Using Moodle [http://moodle.org/course/view.php?id=5 Activity modules] forum
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=66165 A new resource type: where do I put the language strings?] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=65986 New Module Template Code for Moodle 1.7] forum discussion

[[Category:Modules]]
[[Category:Modules]]

[[es:Módulos de actividades (desarrollador)]]
[[fr:Modules (développeur)]
[[ja:モジュール (開発者)]]

Activity modules

2007-10-28T21:04:22Z

Mina: French link

'''Activity modules''' reside in the 'mod' directory. Each module is in a separate subdirectory and consists of the following mandatory elements (plus extra scripts unique to each module):

* ''mod.html'' - a form to set up or update an instance of this module
* ''version.php'' - defines some meta-info and provides upgrading code
* ''icon.gif'' - a 16x16 icon for the module
* ''db/'' - SQL dumps of all the required db tables and data (for each database type)
* ''index.php'' - a page to list all instances in a course
* ''view.php'' - a page to view a particular instance
* ''lib.php'' - any/all functions defined by the module should be in here. If the modulename is called widget, then the required functions include:
:* widget_install() - will be called during the installation of the module
:* widget_add_instance() - code to add a new instance of widget
:* widget_update_instance() - code to update an existing instance
:* widget_delete_instance() - code to delete an instance
:* widget_user_outline() - given an instance, return a summary of a user's contribution
:* widget_user_complete() - given an instance, print details of a user's contribution
:* Other functions available but not required are:
:** widget_delete_course() - code to clean up anything that would be leftover after all instances are deleted
:** widget_process_options() - code to pre-process the form data from module settings
:** [[Implementing Reset course functionality in a module|widget_reset_course_form() and widget_delete_userdata()]] - used to implement [[Reset course]] feature.
:* To avoid possible conflict, any module functions should be named starting with widget_ and any constants you define should start with WIDGET_
* ''config.html'' - (optional) a form to set up or update global settings of this module
* ''lang/en_utf8/resource_widget.php'' - (optional) Lastly, each module will have some language files that contain strings for that module.

IMPORTANT: When creating a new module, the new name of the module must not contain numbers or other special characters!

You should also make sure that your activity module provides appropriate support for groups and metacourses.

==See also==

* Tracker issue [http://tracker.moodle.org/browse/CONTRIB-52 CONTRIB-52 Improvements to make NEWMODULE really useful] - including download link for new module template supporting roles, formslib etc. (unfinished)
* http://download.moodle.org/plugins16/mod/NEWMODULE.zip - new module template for versions of Moodle prior to 1.7. Please follow the README instructions inside the zip.
* Using Moodle [http://moodle.org/course/view.php?id=5 Activity modules] forum
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=66165 A new resource type: where do I put the language strings?] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=65986 New Module Template Code for Moodle 1.7] forum discussion

[[Category:Modules]]
[[Category:Modules]]

[[es:Módulos de actividades (desarrollador)]]
[[fr:Développement:Modules]
[[ja:モジュール (開発者)]]

Releases

2007-07-09T07:04:58Z

Mina: /* Moodle 1.8 */

==Release History==

See [[Release_Notes|Release Notes]] for more details.

==Moodle 1.0==
*Moodle 1.0 - 20 August 2002
*Moodle 1.0.1 - 26 August 2002
*Moodle 1.0.2 - 2 September 2002
*Moodle 1.0.3 - 5 September 2002
*Moodle 1.0.4 - 10 September 2002
*Moodle 1.0.5 - 27 September 2002
*Moodle 1.0.6 - 26 October 2002
:: 1.0.6.1 - 6 Nov
:: 1.0.6.2 - 11 Nov
:: 1.0.6.3 - 14 Nov
:: 1.0.6.4 - 25 Nov
*Moodle 1.0.7 - 9 December 2002
*Moodle 1.0.8 - 7 January 2003
*Moodle 1.0.9 - 30 May 2003

==Moodle 1.1==
*Moodle 1.1 - 29 August 2003
*Moodle 1.1.1 - 11 September 2003

==Moodle 1.2==
*Moodle 1.2 - 20 March 2004
*Moodle 1.2.1 - 25 March 2004

==Moodle 1.3==
*Moodle 1.3 - 25 May 2004
*Moodle 1.3.1 - 4 June 2004
*Moodle 1.3.2 - 9 July 2004
*Moodle 1.3.3 - 16 July 2004
*Moodle 1.3.4 - 11 August 2004

==Moodle 1.4==
*Moodle 1.4 - 31 August 2004
*Moodle 1.4.1 - 12 September 2004
*Moodle 1.4.2 - 5 November 2004
*Moodle 1.4.3 - 21 December 2004
*Moodle 1.4.4 - 7 March 2005
*Moodle 1.4.5 - 7 May 2005

==Moodle 1.5==
*Moodle 1.5 - 5 June 2005
*Moodle 1.5.1 - 8 July 2005
*Moodle 1.5.2 - 16 July 2005
*Moodle 1.5.3 - 11 November 2005
*Moodle 1.5.4 - 21 May 2006

==Moodle 1.6==
*Moodle 1.6 - 20 June 2006
*Moodle 1.6.1 - 20 July 2006
*Moodle 1.6.2 - 12 September 2006
*Moodle 1.6.3 - 10 October 2006
*Moodle 1.6.4 - 17 January 2007
*Moodle 1.6.5 - 30 March 2007

==Moodle 1.7==
*Moodle 1.7 - 7 November 2006
*Moodle 1.7.1 - 17 January 2007
*Moodle 1.7.2 - 30 March 2007

==Moodle 1.8==
*Moodle 1.8 - 30 March 2007
*Moodle 1.8.1 - 14 June 2007
*Moodle 1.8.2 - 8 July 2007

[[Category:Administrator]]
[[Category:Developer]]

[[fr:Historique des versions]]
[[es:Historia de las versiones]]

Roadmap

2006-07-05T14:10:21Z

Mina: French link

This roadmap collects the best information about upcoming features in Moodle. It is not 100% certain - features may change according to available funding and developers.

== Version 1.7 - Expected August 2006 ==

* [[Roles]] - Moodle.com
::This new system will allow the creation of custom roles at site, course and activity level
* [[Accessibility]] - Moodle.com
::Full compliance with all major accessibility standards
* [[XML Database Schema]] - Moodle.com
::Conversion to full database independence using new XML schema for ADOdb. This will give us support for MS SQL, Oracle etc.
* [[Repository API]] - Open University
::Abstract all file operations to an API that allows plugins for different external repositories
* [[Gradebook]] - Arab Open University
::The gradebook system will be revamped for performance, switching from our older "pull" model to a "push" model where all modules will now publish grades as necessary into a central table.
* [[Multi Authentication]] - Iñaki Arenaza?
* [[Learning Design export]] - Moodle.com and Open University of The Netherlands
::We plan to have a very simple export for any Moodle course into IMS LD format, as a proof of concept and to help the community start learning about IMS LD.

== Version 2.0 - Expected early 2007 ==

* [[IMS Learning Design]] - Moodle.com
::Support for importing/exporting LD, converting Moodle activities and sequences of activities into a standard format for sharing, and importing standard sequences into Moodle courses
* [[Conditional activities]] - Moodle.com
::Allowing dependencies and forced paths through the content
* [[Metadata]] - Moodle.com
::Build on the keywords in 1.6 to provide metadata for all activities and courses, linkable to standard lists of metadata such as State-based learning outomes and curricula
* [[Web Services API]]
::Providing remote control and access of Moodle services by other systems, as well as sharing of information between Moodle sites with trust relationships.
* [[Student Information API]]
::API for integrating external systems for managing student information
* [[Community hub]] - Moodle.com
::Leverage above improvements into a system to network Moodles together

== Version 2.1 ==

* [[Site groups|Groups]]
::Groups can also be defined at the site level, and activities can be assigned to course groups
* [[Portfolio API]]
::Interface Moodle activities and repositories to help produce portfolios for internal assessment AND external publication

[[Category:Developer]]

[[es:Planificación]]
[[fr:Planification]]

User:Nicolas Martignoni

2006-06-02T19:13:08Z

Mina:

* Translation of Moodle in french
* Sysop of french [[:fr:Accueil|Moodle Docs]]
* My [http://moodle.org/user/view.php?id=6406&course=5 user profile] on moodle.org

=== Some useful pages ===

* [[Special:Allpages%26from%3D%26namespace%3D10|Templates]]
* [[Special:Categories|Categories]]
* [[Special:Disambiguations|Disambiguations]]

[[fr:User:Nicolas Martignoni]]

User:Nicolas Martignoni

2006-04-23T08:48:30Z

Mina: /* Some useful pages */

Latest release notes

2006-04-10T12:30:11Z

Mina: Link to french Moodle Docs

{{About Moodle}}

==Moodle 1.6 (Coming soon, currently in Beta testing status)==

===New features===

* [[UTF-8 migration|Unicode]]
::Moodle is now 100% Unicode, which means any language can be mixed together and an end to a number of problems that different character sets caused us.
* [[MoodleDocs development|Documentation]]
::A new one-stop wiki site for ALL Moodle documentation, including links from Moodle itself
* [[Database module]]
::A new activity module that allows collaborative collection of structured data, useful for many things!
* [[LAMS]]
::Integrated via a course format and an activity module
* [[Blogs]]
::Allows reflection on an ongoing basis. Entries are marked and can be viewed by user, course, group, site etc. Contains first new support for [[Tags]].
* [[Reports]]
::All reports are now centralised under Course reports and Admin reports. New reports can be written as plugins and dropped in very easily. One big new report is the new course-based statistics system from Catalyst.
* [[My Moodle]]
::A dashboard interface that allows an overview for each user of all their courses etc.
* [[Hive integration]]
::This initial integration with Hive allows teachers to upload, browse, search and select [[Resources|resources]] within the external repository.
* [[Multiple groups]]
::Users can be part of multiple groups within a course
* [[IMS content package]] resource type
::Supports the loading of any content package as a resource, plus special support for a repository of NLN materials
* [[Course backup|Granularised backup]]
* [[Chameleon|Chameleon theme]]
:: An interactive Moodle theme
* [[Enrolment plugins|Multi enrolment]]
::Moodle's enrolment plugins can be used simultaneously on the same site. Also new [[IMS Enterprise]] enrolment plugin.

'''See also'''
*[[Special:Whatlinkshere/Template:Moodle_1.6|List of pages including Moodle 1.6 features]]

==Moodle 1.5.3 (11th November, 2005)==

(Because this release contains important security fixes, we highly advise that sites using any previous version of Moodle upgrade to this version as soon as possible.)

===A few new things===

* We now have SCORM 1.3 (SCORM 2004) support!
* Much improved Assignment grading interface, including "quick grading" options
* A new Single-Sign-On API is available

===Various fixes===

'''General'''

* Contains warnings when Moodle is used on an PHP configuration known to be insecure
* Contains fixes for some recently reported security problems (see [http://security.moodle.org/ security.moodle.org])
* Backups now runs a lot faster medium/large installs. Many issues fixed in this area
* Listing of directory sizes can be made much faster on Linux/Unix servers, thanks to a performance fix you can enable from Admin->Variables: "path_to_du"
* We now log more meaningful IP addresses when the server or the clients are working behind a proxy
* Fixed some issues with PHP accelerators
* Upgrade scripts have been refined and work much better for PostgreSQL installations
* General PostgreSQL port code cleanup
* Upgrading to 1.5.3 will fix any legacy Journal to Online Assignment upgrade issues
* RSS libraries now support RSS 2.0 categories, see bug 3654
* Better accesibilty in file uploads, see bug 3662
* Better support for site-wide HTTPS, see bug 3848
* We now send away bots (like Googlebot) from that try mangled URLs, see bug 3958
* Better DST support for non-logged-in users
* Better DST support for repeat events in Calendar
* Small fixes to the lesson, choice and grade modules
* Minor CSS improvements to formal_white and orangewhite themes
* Better pagination in course listing and loglive pages
* Fixed an IE-only bug related to HTMLArea content where user-edited tables could float and hide part of the UI.

'''Authentication'''

* Fixes to change password/forgotten password with external auth
* Data fetched from external DB or LDAP is now truncated correctly
* Fixed bug 4305 -- better login block behaviour when using secureforms
* Better support for utf-8 user data from external auth
* LDAP: General fixes covering sync_users script and logging of errors
* LDAP: Fixed bug 3141 - Can't update external data with LDAP authentication
* LDAP: Fixed bug 3992 - LDAP password including a quote does not work - credits go to Kita
* LDAP: Better support for ActiveDirectory.
* LDAP: Fixed bug #3594
* LDAP: Better handling of multi-source field mapping
* LDAP: Fix for using DN as idnumber - thanks fo Jeff Graham - http://moodle.org/mod/forum/discuss.php?d=28840

'''Enrolment and metacourses'''

* Metacourses: Prevent normal users to gain access to meta courses via manual enrolment
* Metacourses: better support for MySQL v3.23.x
* DB: Enrolment lookups now work reliably with Moodle on MySQL and Postgres
* DB: Non-MySQL databases work again as external enrolment databases
* LDAP: Fixed a wrong call to add_teacher in LDAP plugin.
* LDAP: Servers being down or unavailable no longer prevent logins
* LDAP: Course auto-creation works again
* LDAP: Fixed several bugs reported by Jeff Graham and Barron Koralesky -- including bugs 3912 and 3974
* LDAP: We can now bind non-anonymously to LDAP
* Authorize.net: several fixes

'''Resources'''

* Bugfix: Avoid linking to empty or unlinkable activity names

'''Forums'''

* Big and small optimizations to tracking of read/unread messages, specially for PostgreSQL
* Fixed some PostgreSQL bugs
* Some more actions are now supported by backup/restore when processing log records, see bug 3582
* Now message forum RSS feeds are including category data -- useful under some RSS agregators able to group messages, see bug 3654
* Fixed paging on forum search

'''Blocks'''

* Several performance improvements
* Fixes to the upgrade process, including PostgreSQL syntax and lower memory usage
* Brought in several bugfixes from 1.6dev
* Fixed bug 3478: Cannot add RSS feed as course creator
* Fixed bug 3793: Prevent warning message when configuring a glossary_random block in a course which has no glossaries

'''Quiz'''

* Some CSS style fixes
* Better compatibility with themes that contain forms in the headers
* Highlighting of correct answers can now be turned off
* Fixed bug 3986: Too many random questions. (mindforge)
* Fixed missing action icons
* Fixed bug 3899 and removed some 'missing course object' messages
* Fixed bug 3950: Ee-attempt button inconsistency for multi-attempt quizzes
* Fixed bug 3953: Quiz/report.php pagesize can be set to 0, credits to Jean-Michel
* Fixed potential data data corruption bug 3915
* Fixed bug 3884: Quiz correct highlights missing for 2 of 3 options.
* Fix for the Student review highlight doesn't seem to work bug
* Fixed bug 3804: Differences in question types between 1.5 and 1.6
* Fixed bug 3822: don't count previews as attempts
* Fixed bug 3807: Question numbering issue
* Fixes for the item analysis plug-in, assembled by Jean-Michel
* Now we reset the timeout counter to avoid timeouts
* Several improvements contributed by Jean-Michel Vedrine. You can now change the number of attempts per page displayed on screen, and download results to Excel/text file, including detailed grades
* Fixed export bug with non-English languages

'''SCORM'''

* We now support SCORM 1.3 (SCORM 2004)!
* Fixed a bug with next and prev SCO search
* Fixed bugs related to masteryscore
* Fixed a problem in AICC course tracking

'''Wiki'''

* Now paging of older versions is showed and working properly, see bug 3750

'''Filters'''

* Mediaplugin filter now finds multi-line links in HTML code
* Censor filter: Added original word as title to the blacked-out version. The filter can obscure actual important words by mistake (eg Dickens) and there needs to be some way to recover the meaning

==Moodle 1.5.2 (16th July, 2005) ==

=== Various fixes ===

* Journal -> Assignment upgrade now works properly :-/
* Assignment submodules now upgrade as expected
* Various other bugs with new Assignments fixed
* Journal module is now disabled by default on new installations
* Login page is now 100% HTTPS if required
* Various small standard theme tweaks
* Fix for recent matching questions display bug in Quiz
* Language editor no longer creates empty files when not necessary (caused country list bug)
* Fixed some manifest parsing problems in SCORM module
* Multilang filter now deals with pack names that contain numbers
* Files are now force-downloaded (fixes IE problems and some security issues)
* Relinking debugging output is escaped
* Large MP3 player now displays ID3 tags properly again
* Some chat daemon improvements

=== Some new things ===

* Orangewhite theme optimised for use on PDA
* Forum user posts page can be called without userid
* Altavista BabelFish now allowed in as guest when Google is

==Moodle 1.5.1 (8th July, 2005) ==

===Various fixes===

* Several potential security problems solved
* Allowobjectembed setting now works correctly
* Speed problem on IE, caused by tab hover fixed.
* Cut and paste in editor on Firefox has a more helpful warning message
* Fixed a session problem when logged on as admin during upgrade from very old Moodle version
* Fixed editing problem in Main menu of site
* Minor CSS display problems in a few areas were fixed
* Fixed the adding of a single discussion forum
* Fixed Lesson problems with calculating grades, and dates
* Fixed Lesson problems with entering a cluster after a page
* Censor filter was fixed to make it work better with old themes

===Some new things===

* New theme: Wood
* Metal theme updated for 1.5
* Many language updates for most languages, including a new language: Khmer
* Block classes can now run custom code when an instance is created/deleted (this is useful for blocks that need to set up non-trivial data structures)
* Wizard for Calculated Questions in Quiz was rewritten
* Backup/Restore module selection is now improved and much easier
* Backup/Restore module has much improved relinking support, it's now faster and easier to implement in new modules

==Moodle 1.5 (5th June, 2005) ==

Here you can find the release notes of the current stable version of Moodle. '''If you experience any bugs in this release, please report them at [http://moodle.org/bugs moodle.org/bugs] so we can fix them in the next release.'''

=== Headline features ===

* Web pages are compliant with XHTML Transitional 1.0
* Improved '''Accessibility''', aiming for compliance with WAI (W3C), SENDA (UK) and Section 508 (US) criteria.
* Very strong '''new Themes system''', allowing cascading themes, user themes, course themes, with very fine control of every page in Moodle via CSS.
* Integrated '''Messaging''' feature for direct communication between all users in the site, featuring realtime popup windows, notification, email copies, blocking, history, WYSIWYG editor, etc
* Forum read/unread tracking with highlights allows you to see new postings at a glance and to control how these are displayed (per forum, per user or per site).
* New '''Blocks''' system, allowing multiple copies of blocks and better block configuration
* Full support for '''Daylight Savings Time''' in every locality around the globe, so everyone always see the correct local time for all events.
* New '''extended gradebook''' allowing custom weighting of different activities, setting extra grades (or taking out others) and improved display and sorting options
* Users can be required to agree to a '''Site Policy
'''

=== Other major system-wide improvements ===

'''Admin'''

* New "maintenance mode" allows the admin to temporarily disable a site (during upgrades, for example).
* Moodle can automatically download a new list of timezones from moodle.org or elsewhere and install it to the database (Olson files are supported too)
* New version of Moodle MySQL Admin module (available separately)
* New calendar options page provides user interface to configure the behavior of the calendar

'''Authentication'''

* New Shibboleth Support
* New CAS Support
* New PAM Support
* Improved LDAP integration, so that LDAP can now control course creation, group assignments. Increased performance and scalability performing user synchronisation.
* Certain user fields can be locked by the admin when using external authentication
* Improved session handling now detects "crossover" sessions that we have found in some buggy PHP installations and prevents them
* Sessions can now be stored in the database (good for clustered installations!)
* Users can be forced to change their password

'''Files'''

* Standardised file browsing in all areas
* Improved uploading, with support for automated Virus scanning of new documents using ClamAV.
* Slasharguments now work also on IIS (upgrade to PHP 4.3.11 needed for ISAPI)

'''Filters'''

* Standardised filter library makes it trivial to write new filters that require searching and highlighting of text.
* Huge efficiency improvements for complex filters like the Glossary filter
* New Tidy filter uses the W3C Tidy program to (optionally) clean all user-entered texts throughout the site and convert it to valid XHTML code
* Improved censorship filter, now "blacks out" words using styles and uses a word list from the language packs.
* Improved Flash MP3 player, now shows progress bar while downloading and playing
* Improved Multi-language filter is faster, more forgiving of syntax errors, and uses new editor-friendly syntax: <span lang="en"></span>
* Auto-linking filters (glossary, activities) can work to link all the occurrences (old behaviour), once for each text block or only once for the whole page ($CFG->filtermatchonepertext, $CFG->filtermatchoneperpage).
* More text can now be filtered in Moodle, including activity names, headings and other such small texts. This makes it possible to design completely multi-lingual sites in Moodle that fully appears in the user's chosen language.

'''Themes'''

* Modules can provide standard styles
* Themes can override required styles of other themes
* Users and courses can choose their own themes if the admin allows it
* Implementation of tabs interface on many pages
* Modules, Blocks and Languages can define their own standard styles

'''HTML Editor'''

* The toolbuttons offered in the editor toolbar are now configurable by the admin
* Search and Replace text within the editor text area (with optional use of regular expressions)

'''Course management'''

* Transparent Blackboard 5.5 course importing (partial 6.0 support)
* The new meta-courses allow to get users automatically enroled in a general course (the metacourse) when enroled in any of the metacourse-linked courses
* New tool to copy content from a course to other.

'''New blocks'''

* HTML block: allowing to place arbitrary content (text, images links) in any course mainpage
* Remote RSS feed: allows to display external news channels inside a Moodle course
* Glossary Selection: to choose and display content from a Moodle glossary in course mainpage

'''Calendar'''

* Major speed improvements for sites with a large number of courses using groups
* Repeating events can now be modified or deleted all at the same time or separately as before
* New "remember filter settings" preference that allows calendar filters to remember their status between logins

=== Activity module improvements ===

'''Assignment'''

* Completely refactored into a new class-based design, allowing new plugin-assignment types
* New Online Text assignment type that doesn't require files and allows inline comments when grading - this new type effectively replaces the old Journal module
* Vastly improved grading interface for handling large classes
* New configuration options to disable late submission and to e-mail alerts to teachers when students submit new work

'''Chat'''

* Streamlined interface looks smoother, works faster, even without using the optional server daemon
* Blocks can now be added to chat pages (e.g. for additional information)

'''Choice'''

* Rewritten to allow any number of choices
* The number of users per choice can be limited, which allows it to be used as tool for "signing up" to an array of options.
* You can now download the results of the choice to XLS or a TXT file

'''Forum'''

* Powerful new Google-like forum searching tools
* Forum read/unread tracking - unread messages are highlighted on the course page, forum page, discussion listing and the discussion view
* The tracking system may be disabled by teachers/users
* User profiles show all posts by a user, as well as all discussions
* When admins edit user messages, a notice is attached
* Discussion listing shows the last user who posted to each discussion and when it was, with a direct link to that post
* In group-enabled forums the discussion listing shows the group the thread applies to, with a link to the group description page.

'''Glossary'''

* New setting to enable/disable the print view of each glossary.
* New search system looks for words everywhere (instead of doing exact phrase match).
* More information is sent to logs to be able to track activity better.

'''Journal'''

* The Journal module has not changed since 1.4, and is now deprecated. The upgrade procedure will convert all your Journal activities into Online Assignments, and hide all the old Journal activities. If you don't want this to happen, then define this in your config.php: $CFG->noconvertjournals = true;

'''Lesson'''

* Now supports timed Lessons
* Can create practice Lessons (grades are not stored)
* Option for students to view points earned while taking the Lesson
* Allow students to review their answers before submitting the Lesson
* New Slide Show Mode (only branch tables are displayed as slides)
* New Left Menu (for enabled branch tables only)
* Lessons can now be Password Protected
* A Tree View can be used for the Lesson creation screen
* Students can post their high scores
* New option to save a Lesson's settings as defaults for new lessons in the same course
* Can delete a student's attempts
* New page Jumps:
** Previous Page
** Unseen question within a branch
** Random question within a branch
** Unseen question within a cluster
* Added functionality to view Lesson statistics
* New question type: Essay. Teachers can view each essay and write comments, assign a grade, and then email it all to the student
* New question creation interface

'''Quiz'''

* Can handle adaptive questions, i.e., questions that allow the student to interact with them repeatedly within the same quiz attempt and that can change in response to student answers.
* Student can be allowed to try a question again immediately within the same quiz attempt until they get the answer right.
* There is a penalty mechanism that deducts a specified fraction of the mark for each wrong attempt at a question.
* Allows questions rendered and scored externally (e.g., by mathematical assessment engines) to be integrated seamlessly into Moodle quizzes via the RQP web services protocol.
* Is prepared for the handling of IMS QTI questions once web services for these become available.
* New tabbed teacher interface for previewing, editing, and reviewing quizzes.
* New "improved security" mode shows quiz in a separate full-screen window, with many browser features disabled
* Quizzes can be presented to students in several pages. The number of questions per page is selectable by the teacher.
* Blocks can now be added to quiz pages (to show results table, or additional information etc)
* Better and cleaner interface for question selection and management in the database. Selected questions can be added to quiz, moved to other categories or deleted en mass.
* Random questions are now added to the quiz question list with a dedicated button, leaving a cleaner interface at questions database without phantom placeholders
* Final grade can be a fractional number, with teacher-defined decimal figures
* Improved results page with user-selectable display of columns, cleaner sorting and new mark display options
* Questions can be edited with one click from the improved quiz preview and question preview screens.
* Questions can be copied with one click, to allow question variations to be created with ease.
* Revamped question categories structures and editing interface.
* Categories now can contain nested subcategories and can be re-ordered.
* It is possible to select whether questions from categories, and or their subcategories are displayed on the question edit page.
* It is now possible to select whether to add random questions from a parent category alone, or from a parent category and its sub-categories.
* Quiz creators are prevented from changing the question set of quizes that have had student responses.
* Recognition, and rejection, of overlapping/redundant questions has been improved.
* The display of questions in longer quiz categories on the quiz editing page is now paginated.
* New export types - IMS QTI (2.0) and xhtml. Improvements & fixes to others.
* New import type - Hot Potato. Improvements & fixes to others.

'''Scorm'''

* The module is now fully conformant with the SCORM 1.2 standard.
* User result data storage and reporting was improved.
* AICC packages can now be imported.

'''Survey'''

* Graph formatting has been improved (labels are more readable)

'''Wiki'''

* Changes to wiki pages are now monitored and displayed in Recent Activity block
* Several under the hood improvements to backup/restore and other routines that enhance the reliability of wikis

== See also ==

*[[Old releases|1.4.5 release notes]]

[[Category:Core]]
[[Category:Administrator]]

[[es:Notas de versiones]]
[[fr:Notes de mise à jour]]

User:Nicolas Martignoni

2006-03-27T06:27:32Z

Mina:

* Translation of Moodle in french
* Sysop of french [[:fr:Accueil|Moodle Docs]]
* My [http://moodle.org/user/view.php?id=6406&course=5 user profile] on moodle.org

Tests

2006-03-16T10:54:50Z

Mina: Add category

This page is currently under construction. More testing plans will be added. You are more than welcome to add any test plan. When we have enough test plans, we would like some help from the community to test each new Moodle release.

This test plan is far from perfect, please feel free to correct any mistake or add some scenarios :-)

These scenarios should be run in Moodle Test Course that can be downloaded [http://download.moodle.org/testcourse/Moodle-tests-course-20060316-1232.zip here]

Here are some general rules:

*Test Case Naming conventions:
[AAA] : 3 Alphabets that represents the module name
[000] : 3 Digits numbers that number the question
[A] : Potential actor = S: student, T: teacher, A: admin

The testing plans are categorized by modules:
* [[Tests/Assignment]]
* [[Tests/Chat]]
* [[Tests/Choice]]
* [[Tests/Forum]]
* [[Tests/Quiz]]
* [[Tests/Resource]]

[[es:Juegos de pruebas]]