MoodleDocs - User contributions [en]

Prototypes

2023-07-03T16:07:04Z

Vmdef: /* Download site migration prototype removed */

This page provides links to prototype sites demonstrating new features that will be included in coming versions of Moodle.

''We would love to hear what you think of these new features! After exploring the sites, please post your feedback in the [https://moodle.org/mod/forum/view.php?id=8052 Future major features forum].''

== New projects and prototype site demonstrations ==
=== Calendar usability improvements ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on updates to the calendar.

The main aims for this project are to make the calendar, calendar block and subscription management more intuitive, easier to use and improve accessibility.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-71770 Tracker epic containing all related issues]
|-
| Prototype
| [https://calendartest.prototype.moodledemo.net/ Calendar usability improvements demo]
|-
| Target Version
| 4.0
|}
=== Course creation improvements ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on making the like easier on creating and editing courses.

The main aims for this project are to improve the user experience of creating and editing courses in Moodle helping teachers to create and organize their courses. Adding new cool features like course index will allow teachers an easy way to view course structure, add new sections and activities, reorganize them and so on.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-70907 Tracker epic containing all related issues]
|-
| Prototype
| [https://createcourse.prototype.moodledemo.net/ Course creation improvements demo]
|-
| Target Version
| 4.0
|}
=== Navigation update ===
{| class="wikitable" border="1"
|-
| Description
| We are updating the navigation around Moodle.

The main aim is to reduce the cognitive load associated with navigating around a Moodle site. For anyone that is new to using our LMS, there are a lot of settings that are immediately present and possibly not relevant. We are going through and improving the layout of the navigation from the front page all the way to how different activities are displaying settings and buttons.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-69588 Tracker epic containing all related issues]
|-
| Prototype
| [https://navigation.prototype.moodledemo.net/ Navigation prototype demo]
|-
| Target Version
| 4.0
|}
=== Timeline block improvements ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on improving the timeline block.

The main aims for this project are to improve the layout of information within the timeline block to make it easier to extract important information, replace pagination with "show more" (lazy-loading) functionality, and to provide bug fixes that improve the overall usability of the block.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-72274 Tracker epic containing all related issues]
|-
| Prototype
|[https://calendartest.prototype.moodledemo.net/ Timeline improvements demo](Note: The timeline features are demonstrated on the same Moodle site as the calendar improvements mentioned above).
|-
| Target Version
| 4.0
|}
=== Site admin presets ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on helping administrators to enable/disable features and plugins easily to simplify their Moodle sites.

The main aim is to adapt and integrate the [https://moodle.org/plugins/block_admin_presets third-party plugin "Admin presets"], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko].
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-72111 Tracker epic containing all related issues]
|-
| Prototype
| [https://siteadminpresets.prototype.moodledemo.net/ Site admin presets demo]
|-
| Target Version
| 4.0
|}
 
== How to contribute ==
=== [[File:logo moodle.png|frameless|100px]] Moodle User Experience (UX) Forums ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX 4.0 release, the UX team are establishing a presence on the Moodle.org platform in order to collaborate and communicate with the wider Moodle Community.
We're looking forward to working with you and sharing what we learn and what we do!
|-
| More
| User Experience Forum [https://moodle.org/course/view.php?id=17248 Want to shape the Moodle future with us?].
|-
| Project Tracker
| Moodle UX 4.0 [https://tracker.moodle.org/projects/UX/issues/ tracker issues and epics]
|-
| Prototypes
| [https://www.figma.com/proto/A4d9WOUVxCqS93mvXVCr8P/4.0-UX-Demo?node-id=2394%3A15559&viewport=727%2C769%2C0.07944665849208832&scaling=scale-down 4.0 Desktop Navigation UX Project]
[https://www.figma.com/proto/A4d9WOUVxCqS93mvXVCr8P/4.0-UX-Demo?node-id=2392%3A11210&viewport=1413%2C310%2C0.31215807795524597&scaling=scale-down 4.0 Mobile Navigation UX Project]
|-
| Target Version
| 4.0
|}
=== [[File:logo_moodle_tracker.jpg|frameless|100px]] Moodle Tracker ===
{| class="wikitable" border="1"
|-
| Description
| This is where we record and manage all issues related to Moodle and related systems.
It's not just for developers! :-) All users should use this system to report problems or new ideas for Moodle and help us make it better.
|-
| More
| Moodle Tracker [https://tracker.moodle.org/secure/Dashboard.jspa Want to shape the Moodle future with us?].
|}
=== [[File:mua-logo-small-onblue.png|frameless|100px]] Moodle Users Association ===
{| class="wikitable" border="1"
|-
| Description
| MUA's mission is to support the growth of Moodle by providing a strong and united voice to users, giving direction and resources for new developments.
|-
| More
| Join MUA [https://moodle.org/course/view.php?id=17248 Shape the future of Moodle today.].
|}
 
 
== [[File:logo_moodle_dev.jpg|frameless|100px]] Other Moodle demo sites ==
=== QA Moodle Demo ===
{| class="wikitable" border="1"
|-
| Description
| It is updated daily at 13:00 UTC with the latest fixes for testers to test and do a final check for any problems.
Every hour (on the hour) the database and files are reset.
|-
| Moodle Version
| The latest Moodle dev release!
|-
|-
| Site
| '''[https://qa.moodledemo.net/ qa.moodledemo.net/]'''
|}
=== School Moodle Demo ===
{| class="wikitable" border="1"
|-
| Description
| This demonstration site gives you the opportunity to explore Moodle in action as a manager, teacher, student, parent or privacy officer with realistic content.
This site is reset every hour on the hour so anything you "break" will get fixed.
|-
| Moodle Version
| The latest Moodle stable release!
|-
|-
| Site
| '''[https://school.moodledemo.net/ school.moodledemo.net/]'''
|}
=== Sandbox Moodle Demo ===
{| class="wikitable" border="1"
|-
| Description
| This site is a plain installation of Moodle using the Boost theme.
This site is reset to its blank state every hour, on the hour.
|-
| Moodle Version
| The latest Moodle stable release!
|-
|-
| Site
| '''[https://sandbox.moodledemo.net/ sandbox.moodledemo.net/]'''
|}
 
==See also==
* [[Roadmap]] - for an overview of new features planned for the next release
* [[Releases]] - for all official releases of Moodle, grouped by branch in reverse chronological order

Prototypes

2023-02-17T09:10:39Z

Vmdef: Added download site prototype

This page provides links to prototype sites demonstrating new features that will be included in coming versions of Moodle.

''We would love to hear what you think of these new features! After exploring the sites, please post your feedback in the [https://moodle.org/mod/forum/view.php?id=8052 Future major features forum].''

== New projects and prototype site demonstrations ==
=== Calendar usability improvements ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on updates to the calendar.

The main aims for this project are to make the calendar, calendar block and subscription management more intuitive, easier to use and improve accessibility.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-71770 Tracker epic containing all related issues]
|-
| Prototype
| [https://calendartest.prototype.moodledemo.net/ Calendar usability improvements demo]
|-
| Target Version
| 4.0
|}
=== Course creation improvements ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on making the like easier on creating and editing courses.

The main aims for this project are to improve the user experience of creating and editing courses in Moodle helping teachers to create and organize their courses. Adding new cool features like course index will allow teachers an easy way to view course structure, add new sections and activities, reorganize them and so on.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-70907 Tracker epic containing all related issues]
|-
| Prototype
| [https://createcourse.prototype.moodledemo.net/ Course creation improvements demo]
|-
| Target Version
| 4.0
|}
=== Navigation update ===
{| class="wikitable" border="1"
|-
| Description
| We are updating the navigation around Moodle.

The main aim is to reduce the cognitive load associated with navigating around a Moodle site. For anyone that is new to using our LMS, there are a lot of settings that are immediately present and possibly not relevant. We are going through and improving the layout of the navigation from the front page all the way to how different activities are displaying settings and buttons.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-69588 Tracker epic containing all related issues]
|-
| Prototype
| [https://navigation.prototype.moodledemo.net/ Navigation prototype demo]
|-
| Target Version
| 4.0
|}
=== Timeline block improvements ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on improving the timeline block.

The main aims for this project are to improve the layout of information within the timeline block to make it easier to extract important information, replace pagination with "show more" (lazy-loading) functionality, and to provide bug fixes that improve the overall usability of the block.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-72274 Tracker epic containing all related issues]
|-
| Prototype
|[https://calendartest.prototype.moodledemo.net/ Timeline improvements demo](Note: The timeline features are demonstrated on the same Moodle site as the calendar improvements mentioned above).
|-
| Target Version
| 4.0
|}
=== Site admin presets ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX improvements for Moodle 4.0, we are working on helping administrators to enable/disable features and plugins easily to simplify their Moodle sites.

The main aim is to adapt and integrate the [https://moodle.org/plugins/block_admin_presets third-party plugin "Admin presets"], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko].
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDL-72111 Tracker epic containing all related issues]
|-
| Prototype
| [https://siteadminpresets.prototype.moodledemo.net/ Site admin presets demo]
|-
| Target Version
| 4.0
|}
=== Download site migration ===
{| class="wikitable" border="1"
|-
| Description
| download.moodle.org is out of the K8's infrastructure and uses Moodle 3.5 version.

The main objective of this project is to upgrade the Moodle instance and move it to the K8 infrastructure, where all the other sites are hosted.
|-
| Project Tracker
| [https://tracker.moodle.org/browse/MDLSITE-7013 Tracker epic containing all related issues]
|-
| Prototype
| [https://download.prototype.moodledemo.net/ Download site demo]
|-
| Target Version
| 4.1
|}
 
 
== How to contribute ==
=== [[File:logo moodle.png|frameless|100px]] Moodle User Experience (UX) Forums ===
{| class="wikitable" border="1"
|-
| Description
| As part of the UX 4.0 release, the UX team are establishing a presence on the Moodle.org platform in order to collaborate and communicate with the wider Moodle Community.
We're looking forward to working with you and sharing what we learn and what we do!
|-
| More
| User Experience Forum [https://moodle.org/course/view.php?id=17248 Want to shape the Moodle future with us?].
|-
| Project Tracker
| Moodle UX 4.0 [https://tracker.moodle.org/projects/UX/issues/ tracker issues and epics]
|-
| Prototypes
| [https://www.figma.com/proto/A4d9WOUVxCqS93mvXVCr8P/4.0-UX-Demo?node-id=2394%3A15559&viewport=727%2C769%2C0.07944665849208832&scaling=scale-down 4.0 Desktop Navigation UX Project]
[https://www.figma.com/proto/A4d9WOUVxCqS93mvXVCr8P/4.0-UX-Demo?node-id=2392%3A11210&viewport=1413%2C310%2C0.31215807795524597&scaling=scale-down 4.0 Mobile Navigation UX Project]
|-
| Target Version
| 4.0
|}
=== [[File:logo_moodle_tracker.jpg|frameless|100px]] Moodle Tracker ===
{| class="wikitable" border="1"
|-
| Description
| This is where we record and manage all issues related to Moodle and related systems.
It's not just for developers! :-) All users should use this system to report problems or new ideas for Moodle and help us make it better.
|-
| More
| Moodle Tracker [https://tracker.moodle.org/secure/Dashboard.jspa Want to shape the Moodle future with us?].
|}
=== [[File:mua-logo-small-onblue.png|frameless|100px]] Moodle Users Association ===
{| class="wikitable" border="1"
|-
| Description
| MUA's mission is to support the growth of Moodle by providing a strong and united voice to users, giving direction and resources for new developments.
|-
| More
| Join MUA [https://moodle.org/course/view.php?id=17248 Shape the future of Moodle today.].
|}
 
 
== [[File:logo_moodle_dev.jpg|frameless|100px]] Other Moodle demo sites ==
=== QA Moodle Demo ===
{| class="wikitable" border="1"
|-
| Description
| It is updated daily at 13:00 UTC with the latest fixes for testers to test and do a final check for any problems.
Every hour (on the hour) the database and files are reset.
|-
| Moodle Version
| The latest Moodle dev release!
|-
|-
| Site
| '''[https://qa.moodledemo.net/ qa.moodledemo.net/]'''
|}
=== School Moodle Demo ===
{| class="wikitable" border="1"
|-
| Description
| This demonstration site gives you the opportunity to explore Moodle in action as a manager, teacher, student, parent or privacy officer with realistic content.
This site is reset every hour on the hour so anything you "break" will get fixed.
|-
| Moodle Version
| The latest Moodle stable release!
|-
|-
| Site
| '''[https://school.moodledemo.net/ school.moodledemo.net/]'''
|}
=== Sandbox Moodle Demo ===
{| class="wikitable" border="1"
|-
| Description
| This site is a plain installation of Moodle using the Boost theme.
This site is reset to its blank state every hour, on the hour.
|-
| Moodle Version
| The latest Moodle stable release!
|-
|-
| Site
| '''[https://sandbox.moodledemo.net/ sandbox.moodledemo.net/]'''
|}
 
==See also==
* [[Roadmap]] - for an overview of new features planned for the next release
* [[Releases]] - for all official releases of Moodle, grouped by branch in reverse chronological order

Travis integration

2020-08-12T15:44:51Z

Vmdef: Settings update

== Moodle core ==

=== Background ===

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

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

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

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

=== Usage ===

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

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

=== Setup ===

# [https://travis-ci.org/auth Sign in to Travis CI] using your GitHub account
# Once you’re signed in, and the initial synchronisation of your GitHub repositories has completed, go to your [https://travis-ci.org/profile profile page]
# Enable Travis CI for your clone of the Moodle repository [[File:moodle-travis-enable.png]]
# Click on the cog icon to configure the Integration
# Ensure that "Build pushed branches" is enabled [[File:moodle-travis-settings-2020.png]]

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

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

== Moodle plugins ==

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

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

=== Ignoring files and folders ===

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

==== Ignoring files ====

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

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

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

== See also ==

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

[[Category:Developer tools]]

File:moodle-travis-settings-2020.png

2020-08-12T15:43:08Z

Vmdef: Travis CI settings for Moodle repositories

Travis CI settings for Moodle repositories

Talk:Travis integration

2020-08-12T15:39:13Z

Vmdef:

{{Note|This page contains previous Travis dev docs. Please move relevant content to [[Travis Integration]] then this page can be deleted.}}

[https://travis-ci.org Travis-ci] is a continuous integration server.

= Moodle core =

Moodle 3.0 comes bundled with a [https://github.com/moodle/moodle/blob/master/.travis.yml .travis.yml file] which executes Moodle's unit tests suite and PHP lint. More checkings might be added in future.

For previous Moodle versions you can either use Moodle 3.0 .travis.yml file (you will probably have to adapt it) or use the following example ([https://github.com/ds125v/moodle-travis/blob/master/.travis.yml]) Signup on Travis, put the .travis.yml file into your repository, link the repository to Travis and Travis will run all your phpunit tests each time you push to your repository.

<code bash>
language: php
php:
- "5.4"
- "5.3"
env:
- DB=mysqli
- DB=pgsql
before_script:
- pear channel-discover pear.phpunit.de
- pear channel-discover pear.symfony.com
- pear install pear.phpunit.de/DbUnit
- phpenv rehash
- cp config-dist.php config.php
- sh -c "sed -i -e s/'password'/''/ -e s/example.com/localhost/ -e s%/home/example%$HOME% -e 's%$\$CFG.*phpu$%\n\1%' config.php"
- sh -c "if [ '$DB' = 'mysqli' ]; then mysql -e 'create database moodle default character set UTF8 collate UTF8_bin;'; fi"
- sh -c "if [ '$DB' = 'mysqli' ]; then sed -i -e s/\'pgsql\'/\'mysqli\'/ -e s/\'username\'/\'root\'/ config.php; fi"
- sh -c "if [ '$DB' = 'pgsql' ]; then psql -c 'create database moodle;' -U postgres; fi"
- sh -c "if [ '$DB' = 'pgsql' ]; then sed -i s/\'username\'/\'postgres\'/ config.php; fi"
- mkdir -m777 $HOME/moodledata
- php admin/tool/phpunit/cli/init.php
</code>

= Moodle plugins =
An example on how to run phpunit/behat tests on travis for a Moodle plugin (here the plugin is the [https://github.com/mouneyrac/moodle-auth_googleoauth2/blob/master/.travis.yml Oauth2 authentication plugin]):
<code bash>
before_install:
- "export DISPLAY=:99.0"
- "sh -e /etc/init.d/xvfb start"
language: php
php:
- "5.4"
env:
- DB=mysqli MOODLE_VERSION=MOODLE_25_STABLE
- DB=mysqli MOODLE_VERSION=master
- DB=pgsql MOODLE_VERSION=MOODLE_25_STABLE
- DB=pgsql MOODLE_VERSION=master
before_script:
- git clone git://github.com/moodle/moodle ../moodle && cd ../moodle
- git checkout $MOODLE_VERSION
- sudo apt-get update > /dev/null
- composer self-update
- composer install --dev --prefer-dist
- mv ../moodle-auth_googleoauth2 auth/googleoauth2
- git clone git://github.com/mouneyrac/moodle-theme_easy theme/oauth2easy
- pear channel-discover pear.phpunit.de
- pear channel-discover pear.symfony.com
- pear install pear.phpunit.de/DbUnit
- phpenv rehash
- cp config-dist.php config.php
- sh -c "sed -i -e s/'password'/''/ -e s/example.com/localhost/ -e s%/home/example%$HOME% -e 's%$\$CFG.*phpu$%\n\1%' config.php"
- sh -c "sed -i -e s/'password'/''/ -e s/example.com/localhost/ -e s%/home/example%$HOME% -e 's%$\$CFG.*bht$%\n\1%' config.php"
- sh -c "if [ '$DB' = 'mysqli' ]; then mysql -e 'create database moodle default character set UTF8 collate UTF8_bin;'; fi"
- sh -c "if [ '$DB' = 'mysqli' ]; then sed -i -e s/\'pgsql\'/\'mysqli\'/ -e s/\'username\'/\'root\'/ config.php; fi"
- sh -c "if [ '$DB' = 'pgsql' ]; then psql -c 'create database moodle;' -U postgres; fi"
- sh -c "if [ '$DB' = 'pgsql' ]; then sed -i s/\'username\'/\'postgres\'/ config.php; fi"
- mkdir -m777 $HOME/moodledata
- php admin/tool/phpunit/cli/init.php
- "(php -S localhost:8000 &) 2> /dev/null > /dev/null"
- "wget http://selenium.googlecode.com/files/selenium-server-standalone-2.31.0.jar"
- "(java -jar selenium-server-standalone-2.31.0.jar &) 2> /dev/null > /dev/null"
- php admin/tool/behat/cli/init.php
script:
- if [ $MOODLE_VERSION = 'master' ]; then vendor/bin/behat --config /home/travis/bht_moodledata/behat/behat.yml --tags @auth_googleoauth2; fi
- phpunit auth_googleoauth2_lib_testcase auth/googleoauth2/tests/lib_test.php
</code>

= Email notifications =
Add to https://docs.moodle.org/dev/Travis_integration#Setup when MDL-52407 is integrated and remove this note after.
# Email notifications will be sent by default to the committer and the commit author. If you want to turn off email notifications for this repository, you can define an environment variable with name MOODLE_EMAIL and no as value.
[[File:environment_variables.png|Define an environment variable]]
= See also =
[https://moodle.org/mod/forum/discuss.php?d=215998 The forum post with the original examples] from David Scotson and Jerome Mouneyrac.

File:environment variables.png

2020-08-12T15:35:26Z

Vmdef: Define an environment variable in Travis CI repository settings.

Define an environment variable in Travis CI repository settings.

Filters

2019-09-09T12:39:24Z

Vmdef: /* Giving your filter a name */

'''Please note:''' This page contains information for developers. You may prefer to read the [[:en:Filters| information about filters for teachers and administrators]].

{{Moodle 2.0}}

'''Filters''' are a way to automatically transform content before it is output. For example
* render embedded equations to images (the TeX filter)
* Links to media files can be automatically converted to an embedded applet for playing the media.
* Mentions of glossary terms can be automatically converted to links.
The possibilities are endless. There are a number of standard filters included with Moodle, or you can create your own. Filters are one of the easiest types of plugin to create. This page explains how.

==Creating a basic filter==

During this tutorial, we will build a simple example filter. We will make one that adds the word 'hello' before every occurrence of the word 'world'.

1. Since our filter is not part of a module, we should put it inside the 'filter' folder. Therefore, we create a directory called 'filter/helloworld'.

2. Inside that folder, we create a file called 'filter.php'.

3. Inside that PHP file, we define a class called filter_helloworld, that extends the moodle_text_filter class. (Note that the file doesn't end by closing the php section with the '?>' tag. This is standard for Moodle and is used to avoid problems with trailing whitespace.)
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
// ...
}

</code>

4. Inside that class, we have to define one method, called 'filter'. This takes the HTML to be filtered as an argument. The method should then transform that, and return the processed text. Replace the '// ...' above with
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
return str_replace('world', 'hello world!', $text);
}
}
</code>

5. version.php
The version.php file keeps track of the version of your module, and other attributes, and is required for newer moodle versions. For a full list of the attributes please see [[version.php]].
Place the version.php in your 'filter/helloworld' directory.
<code php>
defined('MOODLE_INTERNAL') || die();
$plugin->version = 2016052300; // The current plugin version (Date: YYYYMMDDXX)
$plugin->requires = 2016051900; // Requires this Moodle version
$plugin->component = 'filter_helloworld'; // Full name of the plugin (used for diagnostics)
</code>

That is basically all there is to it!

==Giving your filter a name==

To try the new filter, you first have to log in as Administrator and enable it by going to the page Administration ► Plugins ► Filters ► Manage filters.

When you do, you will find that your plugin does not have a name. We missed a step:

6. Inside the 'filter/helloworld' folder, create a folder called 'lang', and in there, create a folder called 'en'.

7. Inside there, create a file called 'filter_helloworld.php'. That is, you have just created the file 'filter/helloworld/lang/en/filter_helloworld.php'.

8. In that file, put
<code php>
<?php

$string['filtername'] = 'Hello world!';
</code>

See [[String API]] for details.

==Trying out your filter==

We had just got to the [[Filters|filters administration screen]]. If you reload that page now, it should now show your filter with its proper name. Turn your filter on now.

Filters are applied to all text that is printed with the [[Output functions|output functions]] format_text(), and, if you have turned on that option, format_string(). So, to see your filter in action, add some content containing the word 'world' somewhere, for example, create a test course, and use the word in the course description. When you look at that course in the course listing, you should see that your filter has transformed it.

==Adding a global settings screen==

Some filters can benefit from some settings to let the administrator control how they work. Suppose we want to greet something other than 'world'. To add global settings to the filter you need to:

9. Create a file called 'filtersettings.php' inside the 'filter/helloworld' folder. Use standard 'settings.php' file in Moodle 2.6 and later.

10. In the 'filtersettings.php' file, put something like:
<code php>
$settings->add(new admin_setting_configtext('filter_helloworld/word',
get_string('word', 'filter_helloworld'),
get_string('word_desc', 'filter_helloworld'), 'world', PARAM_NOTAGS));
</code>

11. In the language file 'filter/helloworld/lang/en/filter_helloworld.php' add the necessary strings:
<code php>
$string['word'] = 'The thing to greet';
$string['word_desc'] = 'The hello world filter will add the word \'hello\' in front of every occurrence of this word in any content.';
</code>

12. Change the filter to use the new setting:
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
$word = get_config('filter_helloworld', 'word');
return str_replace($word, "hello $word!", $text);
}
}
</code>

In standard Moodle, the censor, mediaplugin and tex filters all provide good examples of of how filters use global configuration like this.

==A note about performance==

One important thing to remember when creating a filter is that the filter will be called to transform every bit of text output using format_text(), and possibly also format_string(). That means that you have to be careful, or you could cause big performance problems. If you have to get data out of the database, try to cache it so that you only do a fixed number of database queries per page load. The Glossary filter is an example of this. (I am not sure how good an example ;-))

If your filter uses a special syntax or it is based on an appearance of
a substring in the text, it is recommend to perform a quick and cheap
<tt>strpos()</tt> search first prior to executing the full regex-based search and replace.

<code php>
/**
* Example of a filter that uses <a> links in some way.
*/
public function filter($text, array $options = array()) {

if (!is_string($text) or empty($text)) {
// Non-string data can not be filtered anyway.
return $text;
}

if (stripos($text, '</a>') === false) {
// Performance shortcut - if there is no </a> tag, nothing can match.
return $text;
}

// Here we can perform some more complex operations with the <a>
// links in the text.
}
</code>

==Local configuration==

In addition, in Moodle 2.0, filters can also have different configuration in each context. For example, the glossary filter could be changed so that in Forum A, you can choose to only link words from a particular glossary, say Glossary A, while in Forum B you choose to link words from Glossary B.

To do that sort of thing, you need to add a file called filterlocalsettings.php. In it, you must define a [[lib/formslib.php|Moodle form]] that is a subclass of filter_local_settings_form. In addition to the standard formslib methods, you also need to define a save_changes method. There is not a good example of this in the standard Moodle install yet. To continue our example:

13. Create a file called 'filterlocalsettings.php' inside the 'filter/helloworld' folder.

14. In the 'filterlocalsettings.php' file, put:
<code php>
class helloworld_filter_local_settings_form extends filter_local_settings_form {
protected function definition_inner($mform) {
$mform->addElement('text', 'word', get_string('word', 'filter_helloworld'), array('size' => 20));
$mform->setType('word', PARAM_NOTAGS);
}
}

</code>

15. Extend the filter to use the new setting, if it is present. The filter must be able to work if the setting is not set, for example by falling back to the global or default setting in this case
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
global $CFG;
if (isset($this->localconfig['word'])) {
$word = $this->localconfig['word'];
} else {
$word = $CFG->filter_helloworld/word;
}
return str_replace($word, "hello $word!", $text);
}
}

</code>

==Two types of filter==

In the past, Moodle supported two different types of filter:
* Stand-alone filters like the one we created above. These live in a folder inside the 'filter' folder. For example, in 'filter/myfilter'. 'filter/tex' is an example of a core filter of this type.
* Filters that were part of an activity module. In this case, the filter code lives inside the 'mod/mymod' folder. 'mod/glossary' used to be an example of a core module with a filter.
The second option no longer exists in Moodle 2.5 and later. All filters live in the filter folder. Of course, a filter may depend on an associated other plugin, like mod_glossary. If so, you should declare that in the [[version.php]] file.

==Dynamic content==

From Moodle 2.7:
On (very few) pages - it is possible that page content is loaded by ajax *after* the page is loaded (e.g. equations in a glossary popup). In certain filter types (e.g. MathJax) javascript is required to be run on the output of the filter in order to do the final markup. For these types of filters, a javascript event is triggered when new content is added to the page (the content will have already been processed by the filter in php). The javascript for a filter can listen for these event notifications and reprocess the affected dom nodes.

To subscribe to the event:

// Listen for events triggered when new text is added to a page that needs
// processing by a filter.
Y.on(M.core.event.FILTER_CONTENT_UPDATED, this.contentUpdated, this);

To handle the event:

/**
* Handle content updated events - typeset the new content.
* @method contentUpdated
* @param Y.Event - Custom event with "nodes" indicating the root of the updated nodes.
*/
contentUpdated: function(event) {
var self = this;
Y.use('mathjax', function() {
self._setLocale();
event.nodes.each(function (node) {
node.all('.filter_mathjaxloader_equation').each(function(node) {
MathJax.Hub.Queue(["Typeset", MathJax.Hub, node.getDOMNode()]);
});
});
});
}

See: filter/mathjaxloader/yui/src/loader/js/loader.js

==See also==

* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system
* [[:en:Filters]] user documentation about filters.
* [https://moodle.org/plugins/browse.php?list=category&id=7 - List of filters in the Plugins database].
*[https://github.com/richardjonesnz/moodle_filter_simplemodal - A simple modal filter template using AMD rather than YUI].

[[Category:Filter]]
[[Category:Plugins]]

Filters

2019-09-09T12:35:25Z

Vmdef: Removed the section "Before you start". The Text cache lifetime setting doesn't exist anymore. The only reference I've found is https://moodle.org/mod/forum/discuss.php?d=252426#p1140270.

'''Please note:''' This page contains information for developers. You may prefer to read the [[:en:Filters| information about filters for teachers and administrators]].

{{Moodle 2.0}}

'''Filters''' are a way to automatically transform content before it is output. For example
* render embedded equations to images (the TeX filter)
* Links to media files can be automatically converted to an embedded applet for playing the media.
* Mentions of glossary terms can be automatically converted to links.
The possibilities are endless. There are a number of standard filters included with Moodle, or you can create your own. Filters are one of the easiest types of plugin to create. This page explains how.

==Creating a basic filter==

During this tutorial, we will build a simple example filter. We will make one that adds the word 'hello' before every occurrence of the word 'world'.

1. Since our filter is not part of a module, we should put it inside the 'filter' folder. Therefore, we create a directory called 'filter/helloworld'.

2. Inside that folder, we create a file called 'filter.php'.

3. Inside that PHP file, we define a class called filter_helloworld, that extends the moodle_text_filter class. (Note that the file doesn't end by closing the php section with the '?>' tag. This is standard for Moodle and is used to avoid problems with trailing whitespace.)
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
// ...
}

</code>

4. Inside that class, we have to define one method, called 'filter'. This takes the HTML to be filtered as an argument. The method should then transform that, and return the processed text. Replace the '// ...' above with
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
return str_replace('world', 'hello world!', $text);
}
}
</code>

5. version.php
The version.php file keeps track of the version of your module, and other attributes, and is required for newer moodle versions. For a full list of the attributes please see [[version.php]].
Place the version.php in your 'filter/helloworld' directory.
<code php>
defined('MOODLE_INTERNAL') || die();
$plugin->version = 2016052300; // The current plugin version (Date: YYYYMMDDXX)
$plugin->requires = 2016051900; // Requires this Moodle version
$plugin->component = 'filter_helloworld'; // Full name of the plugin (used for diagnostics)
</code>

That is basically all there is to it!

==Giving your filter a name==

To try the new filter, you first have to log in as Administrator and enable it by going to the page Administration ► Plugins ► Filters ► Manage filters.

When you do, you will find that your plugin does not have a name. We missed a step:

6. Inside the 'filter/helloworld' folder, create a folder called 'lang', and in there, create a folder called 'en'.

7. Inside there, create a file called 'filter_helloworld.php'. That is, you have just created the file 'filter/helloworld/lang/en/filter_helloworld.php'.

8. In that file, put
<code php>
<?php

$string['filtername'] = 'Hello world!';
$string['pluginname'] = 'Hello world!';
</code>

See [[String API]] for details.

==Trying out your filter==

We had just got to the [[Filters|filters administration screen]]. If you reload that page now, it should now show your filter with its proper name. Turn your filter on now.

Filters are applied to all text that is printed with the [[Output functions|output functions]] format_text(), and, if you have turned on that option, format_string(). So, to see your filter in action, add some content containing the word 'world' somewhere, for example, create a test course, and use the word in the course description. When you look at that course in the course listing, you should see that your filter has transformed it.

==Adding a global settings screen==

Some filters can benefit from some settings to let the administrator control how they work. Suppose we want to greet something other than 'world'. To add global settings to the filter you need to:

9. Create a file called 'filtersettings.php' inside the 'filter/helloworld' folder. Use standard 'settings.php' file in Moodle 2.6 and later.

10. In the 'filtersettings.php' file, put something like:
<code php>
$settings->add(new admin_setting_configtext('filter_helloworld/word',
get_string('word', 'filter_helloworld'),
get_string('word_desc', 'filter_helloworld'), 'world', PARAM_NOTAGS));
</code>

11. In the language file 'filter/helloworld/lang/en/filter_helloworld.php' add the necessary strings:
<code php>
$string['word'] = 'The thing to greet';
$string['word_desc'] = 'The hello world filter will add the word \'hello\' in front of every occurrence of this word in any content.';
</code>

12. Change the filter to use the new setting:
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
$word = get_config('filter_helloworld', 'word');
return str_replace($word, "hello $word!", $text);
}
}
</code>

In standard Moodle, the censor, mediaplugin and tex filters all provide good examples of of how filters use global configuration like this.

==A note about performance==

One important thing to remember when creating a filter is that the filter will be called to transform every bit of text output using format_text(), and possibly also format_string(). That means that you have to be careful, or you could cause big performance problems. If you have to get data out of the database, try to cache it so that you only do a fixed number of database queries per page load. The Glossary filter is an example of this. (I am not sure how good an example ;-))

If your filter uses a special syntax or it is based on an appearance of
a substring in the text, it is recommend to perform a quick and cheap
<tt>strpos()</tt> search first prior to executing the full regex-based search and replace.

<code php>
/**
* Example of a filter that uses <a> links in some way.
*/
public function filter($text, array $options = array()) {

if (!is_string($text) or empty($text)) {
// Non-string data can not be filtered anyway.
return $text;
}

if (stripos($text, '</a>') === false) {
// Performance shortcut - if there is no </a> tag, nothing can match.
return $text;
}

// Here we can perform some more complex operations with the <a>
// links in the text.
}
</code>

==Local configuration==

In addition, in Moodle 2.0, filters can also have different configuration in each context. For example, the glossary filter could be changed so that in Forum A, you can choose to only link words from a particular glossary, say Glossary A, while in Forum B you choose to link words from Glossary B.

To do that sort of thing, you need to add a file called filterlocalsettings.php. In it, you must define a [[lib/formslib.php|Moodle form]] that is a subclass of filter_local_settings_form. In addition to the standard formslib methods, you also need to define a save_changes method. There is not a good example of this in the standard Moodle install yet. To continue our example:

13. Create a file called 'filterlocalsettings.php' inside the 'filter/helloworld' folder.

14. In the 'filterlocalsettings.php' file, put:
<code php>
class helloworld_filter_local_settings_form extends filter_local_settings_form {
protected function definition_inner($mform) {
$mform->addElement('text', 'word', get_string('word', 'filter_helloworld'), array('size' => 20));
$mform->setType('word', PARAM_NOTAGS);
}
}

</code>

15. Extend the filter to use the new setting, if it is present. The filter must be able to work if the setting is not set, for example by falling back to the global or default setting in this case
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
global $CFG;
if (isset($this->localconfig['word'])) {
$word = $this->localconfig['word'];
} else {
$word = $CFG->filter_helloworld/word;
}
return str_replace($word, "hello $word!", $text);
}
}

</code>

==Two types of filter==

In the past, Moodle supported two different types of filter:
* Stand-alone filters like the one we created above. These live in a folder inside the 'filter' folder. For example, in 'filter/myfilter'. 'filter/tex' is an example of a core filter of this type.
* Filters that were part of an activity module. In this case, the filter code lives inside the 'mod/mymod' folder. 'mod/glossary' used to be an example of a core module with a filter.
The second option no longer exists in Moodle 2.5 and later. All filters live in the filter folder. Of course, a filter may depend on an associated other plugin, like mod_glossary. If so, you should declare that in the [[version.php]] file.

==Dynamic content==

From Moodle 2.7:
On (very few) pages - it is possible that page content is loaded by ajax *after* the page is loaded (e.g. equations in a glossary popup). In certain filter types (e.g. MathJax) javascript is required to be run on the output of the filter in order to do the final markup. For these types of filters, a javascript event is triggered when new content is added to the page (the content will have already been processed by the filter in php). The javascript for a filter can listen for these event notifications and reprocess the affected dom nodes.

To subscribe to the event:

// Listen for events triggered when new text is added to a page that needs
// processing by a filter.
Y.on(M.core.event.FILTER_CONTENT_UPDATED, this.contentUpdated, this);

To handle the event:

/**
* Handle content updated events - typeset the new content.
* @method contentUpdated
* @param Y.Event - Custom event with "nodes" indicating the root of the updated nodes.
*/
contentUpdated: function(event) {
var self = this;
Y.use('mathjax', function() {
self._setLocale();
event.nodes.each(function (node) {
node.all('.filter_mathjaxloader_equation').each(function(node) {
MathJax.Hub.Queue(["Typeset", MathJax.Hub, node.getDOMNode()]);
});
});
});
}

See: filter/mathjaxloader/yui/src/loader/js/loader.js

==See also==

* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system
* [[:en:Filters]] user documentation about filters.
* [https://moodle.org/plugins/browse.php?list=category&id=7 - List of filters in the Plugins database].
*[https://github.com/richardjonesnz/moodle_filter_simplemodal - A simple modal filter template using AMD rather than YUI].

[[Category:Filter]]
[[Category:Plugins]]

XMLDB defining an XML structure

2018-10-01T09:57:13Z

Vmdef: /* Launching */

[[XMLDB Documentation|XMLDB Documentation]] > [[XMLDB roadmap|Roadmap]] > Defining one XML structure
----

== Justification ==

Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!

One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.

Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the underlying RDBMS being used.

== Implementation ==

Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:

# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.

So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.

== The XMLDB editor ==
[[XMLDB_editor | Main article]]

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically '''long lines''') in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the addition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new '''install.xml''' files, present under each '''db''' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those '''install.xml''' will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

=== Launching ===

Just login to your server as an administrator and, under the Development tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One '''important note''' is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

=== Use===

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.

It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

'''Note: If you can't click on the create links....''' you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver

While editing tables you will see their '''fields''', '''keys''' and '''indexes''' and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.

While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.

One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.

== Conventions ==

Apart of the [[Database| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars. Table names can be at most 28 characters long; column names at most 30 characters.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid to create all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB_Problems#NOT_NULL_fields_using_a_DEFAULT_.27.27_clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

== One example: the assignment module ==

Here we are going to examine the [http://cvs.moodle.org/moodle/mod/assignment/db/install.xml?view=markup current implementation of the XMLDB Schema for the assignment module] (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

* XMLDB
** TABLES, one or more, each one with
*** FIELDS
*** KEYS
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES

First of all you should note that all the elements contain the '''PREVIOUS''' and '''NEXT''' attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the '''COMMENT''' field is present everywhere to be used as desired.

=== The TABLE element ===

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

==== The FIELD element ====

It maps with one field in the DB (obviously). For each field you can define its '''name''', '''type''' (from a list of [[XMLDB column types|neutral types]]), '''length''', '''decimals''' (for some types), '''notnull''' (true/false), '''unsigned''' (true/false), '''sequence''' (if it's autonumeric or serial, true/false) and '''default''' (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

==== The KEY element ====

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its '''name''', '''type''', '''fields''' (that belongs to it) and optionally (if the key is one FK) the target '''reftable''' and '''reffields'''.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

==== The INDEX element ====

Where all the indexes will be defined. For each index you can define its '''name''', '''unique''' (true/false) and the '''fields''' (as a comma-separated string) that it comprises. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

=== The STATEMENT element ===

This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).

Every statement is a collection of '''sentences'''

==== The SENTENCE element ====

Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:

INSERT INTO log_display

and then the text will be added to create this:

INSERT INTO log_display
(module, action, mtable, field)
VALUES
('assignment', 'view', 'assignment', 'name')

There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://cvs.moodle.org/moodle/lib/db/install.xml?view=co Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:

<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>

Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.

== DTD and XML schema ==

Not sure if this will be usable for somebody but here you can find one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.dtd?view=co automatically generated DTD] for the XMLDB files. Also one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.xsd?view=co automatically generated XML Schema] is available. Any improvement/fix to them will be welcome!

== See also ==

* [[XMLB List of files to create|List of files to create]]: The list of files to be created from scratch. Used to follow the progress.
* http://www.hitsw.com/xml_utilites/: One online XML-DTD-Schema converter.

[[Category:XMLDB]]
[[Category:DB]]

Deprecation

2018-07-11T11:03:44Z

Vmdef: /* Step 1. Immediate action */

== What is deprecation? ==

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

== Why is deprecation needed? ==

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

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

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

== Moodle Core deprecation process ==

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

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

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

=== Step 1. Immediate action ===

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

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

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

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

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

=== Step 2. Final deprecation ===

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

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

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

== See also... ==

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

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