MoodleDocs - User contributions [en]

Windows installation

2014-05-12T16:47:02Z

Quen: /* Known problems */

{{Installing Moodle}}

==Known problems==

Windows is not suitable for large Moodle installations because PHP for Windows does not currently support 64-bit numbers, even if it is running on 64-bit Windows. The most significant limitation this causes is a maximum file size of 2GB, which can cause problems (for example) when making backups of large courses. If you require files larger than 2GB, please consider a different operating system.

==Installation Packages==
If you are running a small (less than 30 users) Moodle server or just want to test Moodle on your Windows PC, pre-built packages are available for you to use. Here are links to pages containing step-by-step instructions for installing Moodle using install packages:

*[[Complete install packages for Windows]] for most Windows versions
*[[Windows installation using Git|Installation guide for Windows using WAMP and Git]] How to install Moodle on your Windows PC and update it regularly via Git.

*[[Windows installation using XAMPP|Installation guide for Windows using XAMPP]] A more typical webserver installation than a complete install package. Both use XAMPP.

*[[Installation guide for Windows using EasyPHP]]

== Manual Installation ==
For medium to large installations (e.g. a college, university or business), it is best practice to install Moodle on your server manually.

* '''Plan your system capacity'''. This involves estimating the appropriate hardware to support the number of users in your organisation. See [[Installing Moodle#How_many_users.3F| Installing Moodle ]] in the How Many Users section for a method of doing this.
* '''Install your database server'''. You have a choice of [http://dev.mysql.com/downloads/ MySQL]/[http://mariadb.org/ MariaDB] (recommended), [http://www.postgresql.org/download/ PostgreSQL] (recommended), [[Installing MSSQL for PHP | Microsoft SQL Server 2005]] or Oracle (not recommended).
* '''Install your web server'''. You have several choices - the decision as to which one to use will depend on your in-house expertise and your required level of sustainability:
**Apache 2 is recommended as the most tested and popular for Moodle installations. See these instructions for [[Installing Apache on Windows |manually installing Apache 2 on Windows]].
**[[IIS]] 7 server can also be used. See the Windows forum for guidance on installation and, in particular, permission settings for using Moodle with IIS and CGI timeouts.
**Other webservers are known to install on Windows, e.g. Lighttpd, so you may wish to experiment with these if available memory is low on your server.
* '''Install PHP'''. Use Microsoft Web Platform Installer when using [[IIS]] server.
* '''Install Moodle''' by getting the standard installation for Moodle from [http://download.moodle.org/ http://download.moodle.org/] and read [[Installing Moodle]] which has detailed generic information.
* '''Setup backups'''. Once Moodle is setup and configured, you should setup backups of the system in case of failure or loss of data.
** '''To perform full site backups''' you need to backup the moodledata and moodle directories, Apache webserver configuration (httpd.conf) if you're using Apache, PHP configuration (php.ini) and any php extensions which are non-standard, and the mysql database. To do this use the integrated backup program (Start -> All Programs -> Accessories -> System Tools -> Backup) or your own proprietary backup software (e.g. BackupExec). To backup your mysql database see the [[Backup and restore FAQ]].
** '''To perform course backups''' see the [[Course backup]] page.
** You should also perform a '''state backup''' of the [http://technet2.microsoft.com/WindowsServer/en/library/921f0ed5-523d-48ac-8825-e850b0e548841033.mspx?mfr=true server] or [http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/ntbackup_backup_sysstate.mspx?mfr=true PC]. This is especially important if you're using IIS as this will backup the IIS metabase.
* '''Check your server security and performance'''. It is also good practice to read the [[Performance]] and [[Security]] documentation. Although much of the content is targeted at Linux/Unix users, there is a growing amount for Windows systems.
* Set-up your '''Active Directory authentication'''. You can use the standard [[LDAP authentication]] which prompts users with a username/password, or [[NTLM authentication | integrated NTLM authentication]] which does not require campus users to enter their credentials.

== See also ==

* [[Manual install on Windows 7 with Apache and MySQL]]
* [[Installing APC in Windows]] contains instructions for using a PHP accelerator to reduce processor load.
* [http://moodle.org/mod/forum/discuss.php?d=56835 Running Apache and IIS on the same server] forum discussion.

Windows installation

2014-05-12T16:46:22Z

Quen: Corrected paragraph about Windows 32-bit limit

{{Installing Moodle}}

==Known problems==

Windows is not suitable for large Moodle installations because PHP for Windows does not currently support 64-bit numbers even in 64-bit Windows. The most significant limitation this causes is a maximum file size of 2GB, which can cause problems (for example) when making backups of large courses. If you require files larger than 2GB, please consider a different operating system.

==Installation Packages==
If you are running a small (less than 30 users) Moodle server or just want to test Moodle on your Windows PC, pre-built packages are available for you to use. Here are links to pages containing step-by-step instructions for installing Moodle using install packages:

*[[Complete install packages for Windows]] for most Windows versions
*[[Windows installation using Git|Installation guide for Windows using WAMP and Git]] How to install Moodle on your Windows PC and update it regularly via Git.

*[[Windows installation using XAMPP|Installation guide for Windows using XAMPP]] A more typical webserver installation than a complete install package. Both use XAMPP.

*[[Installation guide for Windows using EasyPHP]]

== Manual Installation ==
For medium to large installations (e.g. a college, university or business), it is best practice to install Moodle on your server manually.

* '''Plan your system capacity'''. This involves estimating the appropriate hardware to support the number of users in your organisation. See [[Installing Moodle#How_many_users.3F| Installing Moodle ]] in the How Many Users section for a method of doing this.
* '''Install your database server'''. You have a choice of [http://dev.mysql.com/downloads/ MySQL]/[http://mariadb.org/ MariaDB] (recommended), [http://www.postgresql.org/download/ PostgreSQL] (recommended), [[Installing MSSQL for PHP | Microsoft SQL Server 2005]] or Oracle (not recommended).
* '''Install your web server'''. You have several choices - the decision as to which one to use will depend on your in-house expertise and your required level of sustainability:
**Apache 2 is recommended as the most tested and popular for Moodle installations. See these instructions for [[Installing Apache on Windows |manually installing Apache 2 on Windows]].
**[[IIS]] 7 server can also be used. See the Windows forum for guidance on installation and, in particular, permission settings for using Moodle with IIS and CGI timeouts.
**Other webservers are known to install on Windows, e.g. Lighttpd, so you may wish to experiment with these if available memory is low on your server.
* '''Install PHP'''. Use Microsoft Web Platform Installer when using [[IIS]] server.
* '''Install Moodle''' by getting the standard installation for Moodle from [http://download.moodle.org/ http://download.moodle.org/] and read [[Installing Moodle]] which has detailed generic information.
* '''Setup backups'''. Once Moodle is setup and configured, you should setup backups of the system in case of failure or loss of data.
** '''To perform full site backups''' you need to backup the moodledata and moodle directories, Apache webserver configuration (httpd.conf) if you're using Apache, PHP configuration (php.ini) and any php extensions which are non-standard, and the mysql database. To do this use the integrated backup program (Start -> All Programs -> Accessories -> System Tools -> Backup) or your own proprietary backup software (e.g. BackupExec). To backup your mysql database see the [[Backup and restore FAQ]].
** '''To perform course backups''' see the [[Course backup]] page.
** You should also perform a '''state backup''' of the [http://technet2.microsoft.com/WindowsServer/en/library/921f0ed5-523d-48ac-8825-e850b0e548841033.mspx?mfr=true server] or [http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/ntbackup_backup_sysstate.mspx?mfr=true PC]. This is especially important if you're using IIS as this will backup the IIS metabase.
* '''Check your server security and performance'''. It is also good practice to read the [[Performance]] and [[Security]] documentation. Although much of the content is targeted at Linux/Unix users, there is a growing amount for Windows systems.
* Set-up your '''Active Directory authentication'''. You can use the standard [[LDAP authentication]] which prompts users with a username/password, or [[NTLM authentication | integrated NTLM authentication]] which does not require campus users to enter their credentials.

== See also ==

* [[Manual install on Windows 7 with Apache and MySQL]]
* [[Installing APC in Windows]] contains instructions for using a PHP accelerator to reduce processor load.
* [http://moodle.org/mod/forum/discuss.php?d=56835 Running Apache and IIS on the same server] forum discussion.

Upgrading

2014-04-29T09:45:25Z

Quen: /* Check the requirements */

{{Installing Moodle}}
''This page explains in detail how to upgrade Moodle. For a summary of the process, see [[Upgrade overview]].''

==Check the requirements==

Check that your server meets all requirements for 2.7 in ''Administration > Site administration > Server > [[Environment]]''.

Note: You can only upgrade to Moodle 2.7 from Moodle 2.2 or later. If upgrading from earlier versions, you must [https://docs.moodle.org/22/en/Upgrading_to_Moodle_2.2 upgrade to 2.2] as a first step.

==Before upgrading==

'''We advise that you test the upgrade first on a COPY of your production site, to make sure it works as you expect.'''

===Themes===

All core themes, except clean, have been removed from Moodle 2.7. Thus sites using any core theme (including sites using a core theme as a parent theme) other than clean must do the following:

# Download the 2.7 version of your theme as a zip file from the [https://moodle.org/plugins/browse.php?list=category&id=3 Themes section of the Moodle plugins directory].
# Follow the steps above to install the new Moodle software. In step 4, unzip the theme and copy it to moodle/theme/.
# Proceed with the upgrade.

Note: Only installed add-on themes may be updated automatically during the upgrade, NOT core themes. Because core themes have been removed from Moodle 2.7, they have to be re-added.

===Questions===

In Moodle 2.1 there was a major upgrade to questions. As explained in [https://docs.moodle.org/21/en/Upgrading_to_Moodle_2.1#Planning_the_question_engine_upgrade the upgrade documentation for that version], it was possible to delay parts of the database upgrade to be run later. Before you upgrade to Moodle 2.7, this upgrade must be completed. You can check for this by looking at the bottom of the [[Environment]] check page in your site.

== Backup important data ==

There are three areas that should be backed up before any upgrade:
#Moodle software (For example, everything in server/htdocs/moodle)
#Moodle uploaded files (For example, server/moodledata)
#Moodle database (For example, your Postgres or MySQL database dump)

See [[Site backup]] for more specific information.

==Put your site into maintenance mode==
Before you begin upgrading your site, you should put it into [[Maintenance_mode | maintenance mode]] to stop any non-admin users from logging in.

== Check for add-on updates ==

If you have [[Automatic updates deployment]] enabled, you will be able to update installed add-ons automatically during the upgrade. Just make sure you check for available updates (via the button for it) at the Plugins check screen.

If you are updating add-ons manually, it is a good moment now to check in the [http://moodle.org/plugins Moodle Plugins directory] whether there is a 2.7 version available for any add-ons (including themes) that you have previously installed on your site. If so, download the add-on package. In the next step, you will copy it to the appropriate location in your Moodle code (see [[Installing add-ons]]).

The upgrade of the add-on will then happen as part of the Moodle upgrade process.

If an out-of-date add-on causes your upgrade to fail, you can usually delete the add-on code rather than uninstalling it from within Moodle so that the data associated with it is not deleted.

== Install the new Moodle software ==

=== Standard install package ===

# Move your old Moodle software program files to another location. ''Do NOT copy new files over the old files.''
# Unzip or unpack the upgrade file so that all the new Moodle software program files are in the location the old files used to be in on the server. Moodle will adjust SQL and moodledata if it needs to in the upgrade.
# Copy your old [[Configuration file|config.php file]] back to the new Moodle directory.
# As mentioned above, if you had installed any custom add-ons on your site you should add them to the new code tree now. It is important to check that you get the correct version for your new version of Moodle. Be particularly careful that you do not overwrite any code in the new version of Moodle.
# Dont forget to also copy over your moodledata folder / directory. If you don't you will get a "fatal error $cfg- dataroot is not configured properly".

====Linux====
mv moodle moodle.backup
tar xvzf moodle-2.7.tgz

Next, copy across your config.php, any custom plugins, and your .htaccess file if you created one ('''check that custom plugins are the correct version for your new Moodle first'''):

cp moodle.backup/config.php moodle
cp -pr moodle.backup/theme/mytheme moodle/theme/mytheme
cp -pr moodle.backup/mod/mymod moodle/mod/mymod

Don't forget to make moodle/config.php (and the rest of the source code) readable by your www server. Ideally the files should not be writeable by your server.

If you use cron, take care that cron.php is executeable and uses the correct php command:
chmod 740 admin/cli/cron.php (some configurations need chmod 750 or chmod 755)
copy the first line from cron.php (if it looks like '#!/usr/local/bin/php' or '#!/usr/local/bin/php5.3', no need to copy '<?php')

if necessary.

=== Using Git ===

You can use Git for updating or upgrading your Moodle. See [[Git for Administrators]] for details.

===Command line upgrade===

On Linux servers, Moodle 2.7 supports running the [[CLI|upgrade from the command line]], rather than through a web browser. This is likely to be more reliable, particularly for large sites.

== Finishing the upgrade ==

The last step is to trigger the upgrade processes within Moodle.

To do this just go to ''Administration > Site administration > Notifications''.

Moodle will automatically detect the new version and perform all the SQL database or file system upgrades that are necessary. If there is anything it can't do itself (very rare) then you will see messages telling you what you need to do.

Assuming all goes well (no error messages) then you can start using your new version of Moodle and enjoy the new features!

Note: If you are running multiple servers then you should purge all caches manually (via ''Administration > Site administration > Development > Purge all caches'') after completing the upgrade on all servers.

===Fatal error: Maximum execution time of 30 seconds exceeded...===

If your server uses a main language other than English, you may encounter a 'Fatal error: Maximum execution time of 30 seconds exceeded' when you try to upgrade it. You can increase max_execution_time = 160 on php.ini to allow the scripts enough time to process the language update. Otherwise, you can switch to English as the default language before doing the upgrade and back to your original language after a succcessful upgrade. See the forum discussion at https://moodle.org/mod/forum/discuss.php?d=119598.

==After upgrading==

The config.php file from your installation should work fine but if you take a look at config-dist.php that came with Moodle 2.7 there are more/different options available (e.g. database drivers and settings). It's a good idea to map your old config.php settings to a new one based on the 2.7 config-dist.php.

===Assignments===

The old assignment (2.2) module has been removed from core and has been replaced by a stub to support transparently remapping URLs and restoring course backups from the old module to the new one.

If you are still using the old assignment (2.2) module, after upgrading to Moodle 2.7 all assignment (2.2) activities will be hidden. You need to run the [[Assignment upgrade tool]] to un-hide the activities.

If you really, really need to keep using the old assignment (2.2) module, you should update the code to Moodle 2.7, and then replace the "mod/assignment" folder with the one from the plugins directory before completing the upgrade.

==Possible issues that may affect you in Moodle 2.7==

''Items to be added here...''

=== Moodle 2.3, 2.4, 2.5 and 2.6 improvements ===

Depending on which version you are upgrading from, please see the section 'Possible issues that may affect you' in the documentation

* [https://docs.moodle.org/23/en/Upgrading Upgrading to Moodle 2.3]
* [https://docs.moodle.org/24/en/Upgrading Upgrading to Moodle 2.4]
* [https://docs.moodle.org/25/en/Upgrading Upgrading to Moodle 2.5]
* [https://docs.moodle.org/26/en/Upgrading Upgrading to Moodle 2.6]

==See also==

* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[dev:Moodle 2.7 release notes|Moodle 2.7 release notes]]
* [[dev:Upgrade API|Upgrade API]]

[[es:Actualización de moodle]]
[[fr:Mise à jour]]
[[ja:Moodleをアップグレードする]]
[[de:Aktualisierung von Moodle]]

Talk:Restrict access settings

2014-04-25T17:13:35Z

Quen: Created page with "==sam comments== Thanks for your work on this documentation! I had a look at the page and I have a few minor comments: 1) "It may be hidden from students on the course page ..."

==sam comments==

Thanks for your work on this documentation! I had a look at the page and I have a few minor comments:

1) "It may be hidden from students on the course page by clicking the eye:"

As the eye is the hardest part to understand, it may be worth ensuring this part of the documentation is accurate and complete (because it's the sort of thing people might hit up the documentation for). I'm not a documentation expert so I didn't want to change it directly but here's what the eye icon actually does:

* If the eye is SHUT then students who do not meet that part of the condition will not see the activity at all.
* If the eye is OPEN the students who do not meet that part of the condition will see the activity but it will be greyed out and have information about why they can't access it yet.

The shut eye takes precedence. For example, you could have 2 conditions, one based on date (with eye shut) and one based on completing a previous activity (with eye open). That way, the activity will not appear at all until the date; then it will appear but tell you that you need to complete the other activity; then when you complete the other activity you can access it.

For OR and NOT AND type conditions, you only get a single eye icon instead of one for each condition (it doesn't logically make sense if there are multiple ones in those cases).

There is a really good reason for this to be as complicated as it is, honest. :)

2) At present you've left the old documentation and screenshot in there for the section settings. In 2.7 the section interface is the same as the activity interface.

3) I wonder if it is worth mentioning that certain restriction options are not always available. (In other words, whether 'there are loads of buttons on your screenshot but I only have 3' might become an FAQ) depending on whether they make sense for your situation. For example the group/grouping buttons are available but only if you actually have group/groupings in the course (and you haven't turned on the old 'groupmembersonly' option). The activity completion option is only available if you turned on activity completion/progress for the course. Not sure this needs mentioning as may be obvious.

[[User:sam marshall|sam marshall]] ([[User talk:sam marshall|talk]]) 01:13, 26 April 2014 (WST)

Session handling

2014-02-04T10:58:09Z

Quen: /* Memcached */

{{Server settings}}
An administrator can change the following settings in ''Administration > Site administration > Server > Session Handling''.

Once someone logs in to your Moodle server, the server starts a session. The session data allows the server to track users as they access different pages.

==Use database for session information==

Moodle needs to store the session data in some storage. By default either file or database session storage is selected, this option allows admin to change it. Large installation should use memcached driver described below.

Note that this option disappears after setting the $CFG->session_handler_class in config.php file.

==Timeout==

If users don't load a new page during the amount of time set here, Moodle will end their session and log them out.

Be sure this time frame is long enough to cover the longest test your teachers may offer. If a student is logged out while they are taking a test, their responses to the test questions may be lost.

==Cookie prefix==

Most of the time, you can leave this blank, unless you are running more than one Moodle site on the same server. In this case, you will want to customize the name of the cookie each Moodle site uses to track the session. This enables you to be logged into more than one Moodle site at the same time.

Note: If you change "Cookie prefix" or "Cookie path" you will need to login again as the changes take effect immediately.

==Cookie path==

The relative path to this Moodle installation, this may be used to force sending of Moodle session cookie to parent directories. Invalid values are ignored automatically.

==Cookie domain==

This can be used to send session cookies to higher domains instead of just the server domain. This may be useful for some SSO solutions. Invalid values are ignored automatically.

==Session drivers==
User sessions may be stored in different backends. Session drivers can be configured only in config.php file - see examples in config-dist.php file.

===Memcached===
Memcached session driver is the fastest driver, it requires external memcached server and memcached PHP extension. Server cluster nodes must use shared session storage.

Configuration options in config.php:
<code php>
$CFG->session_handler_class = '\core\session\memcached';
$CFG->session_memcached_save_path = '127.0.0.1:11211';
$CFG->session_memcached_prefix = 'memc.sess.key.';
$CFG->session_memcached_acquire_lock_timeout = 120;
$CFG->session_memcached_lock_expire = 7200; // Ignored if memcached extension <= 2.1.0
</code>

Notes:
* Make sure the memcached server has enough memory.
* Use different prefix when storing sessions from multiple Moodles in one server.
* If memcached extension <= 2.1.0 the locking works differently from other drivers, the lock is expired/released at the end of timeout - see MDL-42485.
* Unlike the caching infrastructure there is currently no driver for memcache, only memcached.

===Files===
This driver is used by default in new installation.

Configuration options in config.php:
<code php>
$CFG->session_handler_class = '\core\session\file';
$CFG->session_file_save_path = $CFG->dataroot.'/sessions';
</code>

Notes:
* File based sessions require file system that supports file locking.

===Database===
This type of driver was used by default in Moodle 2.0-2.5

<code php>
$CFG->session_handler_class = '\core\session\database';
$CFG->session_database_acquire_lock_timeout = 120;
</code>

Notes:
* DB sessions are not compatible with MyISAM database engine.
* If you are using MySQL/MariaDB make sure that \'max_allowed_packet\' in my.cnf (or my.ini) is at least 4M.
* The performance is relatively low, it is not recommended for large sites.

==See also==

*[[Sessions FAQ]]

[[cs:admin/setting/sessionhandling]]
[[ja:セッションハンドリング]]
[[de:Sitzungsinformationen]]

Experimental settings

2013-11-15T12:23:43Z

Quen:

{{Developer tools}}
An administrator can enable certain experimental features in ''Settings > Site administration > Development > Experimental > Experimental settings''.

An experimental feature is defined as a feature which require additional testing and bug-fixing.

*[[Safe exam browser]]
*Group members only - adding the '[[Available for group members only]]' checkbox to the activity settings page
*[[CSS optimiser]] (new in Moodle 2.3)
*Drag and drop upload of text/links (see MDL-22504 for further details)
* New backup format (supports large backups). May become default in a future Moodle version. See [[Backup and restore FAQ#Using the new backup format (experimental)]].

[[es:Configuraciones experimentales]]
[[eu:Esperimentala]]
[[fr:Expérimental]]
[[ja:実験用]]

Backup and restore FAQ

2013-11-15T12:20:43Z

Quen: Added information about using the new backup format for large backups

{{Backup}}
==How do I backup a course?==

See [[Course backup]] and [[Automated backup setup]].

==How do I restore a course?==

See [[Course restore]].

==How do I backup my site?==

See [[Site backup]].

==What are the pros and cons of course versus site backups?==

[[Site backup|Site backups]] are recommended in order to have all data saved with the best confidence and the shortest recovery time.

For a site administrator, [[Automated course backup|automated course backups]] are more expensive in terms of time, CPU usage and storage. The recovery time to have a site running again takes longer than a site backup. However, teachers and site administrators might find a course backups as a way to create a "fresh" copy of a course that can be re-used (in older versions of Moodle, in newer versions see [[Import course data]]) or as a method to distribute a course(s) to other Moodle sites.

==Why is my automated course backup much smaller in size than my manual course backup?==

This is an intentional design decision. Because of the way files are stored in Moodle 2.x, there is no need to include the files in the backup if you are planning to restore them to the same Moodle site. Leaving them out saves huge amounts of disk space and makes the backup procedure much faster.

==What data is not contained in course backups?==

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.
* Users' passwords are not backed up when the "Include enrolled users" option is selected.

==The process ends with: "Error: An error occurred deleting old backup data". What should I do?==

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

# Delete old records from "backup_ids" table: Check the table exists, repair it and try again.
# Delete old records from "backup_files" table: Check the table exists, repair it and try again.
# Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

[[Image:BackupProblem.gif|thumb|Backup error message]]For points 1 & 2, there are various ways of repairing tables, including using MySQL Admin.
For point 3 see below:

The error message states that the "directory not empty" and gives the path to that directory. If you go there with an FTP program you can see what is there and clean up. It could be just some empty subfolders that were leftover. Deleting these has been able to help. One can also delete the dir "moodledata/temp/backup" completely. That can take a bit longer but may solve several problems at once.

==The process ends with: "XML error: not well-formed (invalid token) at line YYYY". What can I do?==

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but not the folder itself!).

* Restore the course. It should work now.

* Restore still not working? See the next question.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

==The process ends with: "moodle xml not found at root level of zip file". What can I do?==
If you are restoring from a zip file backup make sure the moodle.xml file is at the root level. To ensure this:
#Unzip the backup file of the course (example: mycourse.zip)
#Once the file is unzipped, open the folder (example: mycourse).
#Select the folders within the mycourse folder AND the moodle.xml file and create a zip of those item (example: mycourse_new.zip)
#Upload the new zip file (example: mycourse_new.zip) and restore from that.

If the backup file is guaranteed to be correct, check paths to external files (zip, unzip). Incorrect settings also lead to this error message (see the Using Moodle forum discussion [http://moodle.org/mod/forum/discuss.php?d=140355 moodle.xml not found in root...] and MDL-14812).

==The process ends with: "An error occurred while copying the zip file..."==

This problem is most likely caused by a permissions issue in the destination directory. Backup files are copied to "XXX/backupdata" under your dataroot directory (where XXX is the id of the course being backed up).

The problem could also be caused by a disk being full, though this is far less likely.

To obtain precise information about what's happening, you can enable debug messages in ''Administration > Server > [[Debugging]]'' (select the maximum level - DEVELOPER) and/or check the web server error logs.

==I Still get an XML error. How can I clean the borked XML file?==

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous question. In such cases you may want to try the following:

* Download the [http://repository.atlassian.com/atlassian-xml-cleaner/jars/atlassian-xml-cleaner-0.1.jar Atlassian XML Cleaner Utility] from the [http://confluence.atlassian.com/display/JIRA/Removing+invalid+characters+from+XML+backups JIRA Atlassian site].

* Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

* Rename the unclean moodle.xml file to moodle-unclean.xml.

* If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted character encoding when transferring from an operating system to another.

* Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

* Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

* If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

==What does "Some of your courses weren't saved!!" mean?==

There are three possible causes of this problem:
# Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
# Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking.
# Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

==Why are some courses being skipped?==

Course backups automatically skip courses which are unavailable to students and have not been changed in the time period specified in 'Skip courses not modified' in ''Settings > Site administration > > Courses > Backups > Automated backup setup'' (by default 30 days).

==Why does restore stop, rather than completing?==

Attempting to restore a course to an older version of Moodle than the one the course was backed up on can result in the restore process failing to complete. To ensure a successful restore, make sure that the version of Moodle you are restoring the course to is the same, or newer, than the one the course was backed up on.

If it stop unexpectedly with no errors shown try again with [[Debugging]] switched on. Any errors you now see can help experts in the support forums diagnose your problem. You can also check the discussion links in the See also section below for further advice.

==Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict"==

[[Image:Moodle 2.0 Restore breaks.png|thumb|Error message in Moodle 2.0]]

This message is displayed when:

# The target site has a user xxxx (xxxx being the username)
# The backup archive being restored also contains a user xxxx (same username)
# After various comparisons, Moodle has determined that the target site user xxxx and the backup user xxxx aren't the same person.

If 1, 2 and 3 are all true, the restore process stops in order to prevent the backup user xxxx's activities (forum posts, quiz attempts, assignment uploads, etc) from being associated with the target site user xxxx.

These checks and behaviour were introduced in Moodle 1.9.x and continue being valid under 2.0. It's common for the user in question to be the "admin" user (which exists in practically all Moodle installations).

There are two possible methods to make the xxxx users match (and avoid the conflict):

a) Modify the backup archive '''users.xml''' file and make the ''email'' or ''firstaccess'' fields match the ones in target site.<br />
b) Modify the '''target site''' and set the user ''email'' or ''firstaccess'' fields to match the ones in backup archive users.xml file.

Method a) is recommended so the restore process will match both xxxx users and all activities in the backup file belonging to xxxx will be associated to the already existing target site user xxxx user.

'''NOTE:''' When using method a) be aware that the ''moodle-filename-backup.'''mbz''''' is a zip file and can be renamed to ''moodle-filename-backup.'''zip''''' and unzipped.
When editing is complete, rezip and then rename using the original file name with the "*.mbz" extention.

==Why are certain course links broken in a restored course?==

Inter-activity links must be absolute (full) URLs e.g. <code><nowiki>http://site.com/mod/resource/view.php?id=xxx</nowiki></code> in order to be processed properly during backup and restore.

Any relative URLs e.g. <code>/mod/resource/view.php?id=xxx</code>, <code>../resource/view.php?id=xxx</code> or <code>view.php?id=xxx</code> will result in broken links when the course is restored.

==I have a very large course, over 2GB, and the backup process stops.==

Courses over 4GB cannot be backed up without turning on an experimental option. See 'New backup format' below.

Below that size, large courses can be restored in Moodle, but sometimes it needs a bit of tweaking to get it right. Moodle backup files are *.mbz fies and can be renamed to zip files. They can be unzipped, then edited, rezipped and restored. It does not matter if you are using a Linux or Windows or Mac server, a local host or anything else, the technique is the same.

The editing comes in two different ways, one is the resources, activities, quizzes, images. video files and so on are listed, written and referred to in the moodle.xml file. You can find the starting point and the end point of each resouce that you can delete out of the xml file.

The xml might look something like this:
<file id="111"> <contenthash>b11ac9bc0cebee17acfd28d13b548331f76645bc</contenthash>
<contextid>21</contextid>
<component>mod_resource</component>
<filearea>content</filearea>
<itemid>0</itemid>
<filepath>/</filepath>
<filename>howtomakeatimemachine.flv</filename>
<userid>4</userid>
<filesize>1092320586557</filesize>
<mimetype>video/flv</mimetype>
<status>0</status>
<timecreated>12345432123</timecreated>
<timemodified>12345432123</timemodified>
<source>howtomakeatimemachine.flv</source>
<author>Fred Nurks</author>
<license>allrightsreserved</license>
<sortorder>0</sortorder>
<repositorytype>$@NULL@$</repositorytype>
<repositoryid>$@NULL@$</repositoryid>
<reference>$@NULL@$</reference>
</file>

When editing, make sure all this is deleted, everything between the <file></file> tags.

The second part of editing is locating the actual resouce if it is an image, a separate file or video then deleting it. Really large mbz files tend to have a lot of videos, often flv files, or uncompressed images, like tiffs. They can be found, and deleted easily, in the directory tree of the backup.

You can then rezip the edited file, rename it to an mbz and, if you have edited it right, it should restore. You can use the original file to break down really large backups over and over into four or five smaller mbz files, as many as you like.

It is recommended that you test the technique first on a smaller file, it is easier to follow and gets you used to xml structuring and so on. Say one course with a couple of pages, a number of different image types, a couple of videos will help you immensely.

You do not have to worry about permissions in Windows or Xos servers, or concern yourself with editing rights usually. However, you may be required to ensure you are the owner fo the files being edited.

'''NOTE:''' Before re-zipping, check to make sure you have removed all references to the pages/files/resources you have deleted in the moodle-backup.xml file as well. here msay be none, but check anyway.

== Using the new backup format (experimental) ==

If you have large courses you may find it useful to turn on an experimental option introduced in Moodle 2.6, 'Enable new backup format' (on the admin menu under Development/Experimental/Experimental settings).

This option selects a different internal backup format. Without this option, you cannot back up courses larger than 4GB.

You can change this option at any time. Whatever the option is set to, restore works for both the old and new format. The option only affects newly-created backups.

When you use this option, backup files still have the .mbz extension and work the same way, but there are some differences:

* There is no limit on total backup size. (We have tested with courses up to about 10GB.)
* Files may be slightly smaller.
* If you need to edit this type of backup file manually, you will need to rename the .mbz file to .tar.gz, instead of .zip. You may need to use different software to extract and recompress this type of file. We have tested using GNU tar on Windows and Linux.

The new backup format is experimental, but is being used in some large sites and may be enabled as default in a future Moodle version. If you find problems with it, please report them in the Moodle tracker.

==How can I extract original files from a Moodle backup file?==
If you really want to get original files from the backup file (an ".mbz" file) you downloaded (using the backup and restore feature), you can do so in much the same way as is suggested above.

The backup file can actually be opened with any zip/unzip program you can download. Once you open the file, you need to extract:

The files.xml file.
The files directory (folder).

Next step would be to open the "files.xml" file in a text editor, and:

Search for the name of each file you want to get.
Take note of the value of the corresponding contenthash tag.
In the "files" folder you extracted, locate the file whose name is the same as the value of the contenthash and which will always be located in a folder whose name corresponds to the two first characters of the file name.

For example, let's assume there is a "backup_courses-120730.mbz" file of which the "files.xml" file and the "files" folder have been extracted. There is a PDF file named "Leadership.pdf" that is required for another purpose.

Open the files.xml file and:

1. Search for the string "Leadership.pdf", which in this case is found under the following <file id...> group tag:

<file id="12345">
<contenthash>fb6cf43a9b2d432403c70a2cb4c340dbb6225631</contenthash>
:
<filename>Leadership.pdf</filename>
:
<license>allrightsreserved</license>
<sortorder>1</sortorder>
</file>

2. Take note of the corresponding contenthash value: fb6cf43a9b2d432403c70a2cb4c340dbb6225631.

3. As the first two characters of the contenthash are "fb", open the "fb" folder inside the "files" directory (which was previously extracted), and there is a file named "fb6cf43a9b...". Rename that file as "Leadership.pdf", and then move it to another location. Repeat this for all the files required, using the correct contenthash value of course.
== See also ==

*Using Moodle [http://moodle.org/mod/forum/view.php?f=128 Backup and Restore forum]
*[http://www.databasejournal.com/features/mysql/article.php/10897_3300511_2 databasejournal.com article on repairing database corruption in MySQL]
* [[Site backup]]
* [[Moodle migration]]
* [[Beginning Moodle 2.0 Administration]]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=142720 Trying to restore user 'admin' from backup file will cause conflict]
*[http://moodle.org/mod/forum/discuss.php?d=167471 Where is the Moodle 2.0 "Course Backup Filearea"?]

[[Category:FAQ]]

[[es:FAQ Backup]]
[[pl:Backup FAQ]]
[[fr:FAQ de sauvegarde]]
[[ja:バックアップFAQ]]
[[pt:FAQ sobre cópias de segurança]]

Administration via command line

2013-08-16T10:53:33Z

Quen:

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]

Caching

2013-05-24T09:26:25Z

Quen: Added section about cache lock instances

{{Performance}}

A cache is a collection of processed data that is kept on hand and re-used in order to avoid costly repeated database queries.

Moodle 2.4 saw the implementation of MUC, the Moodle Universal Cache. This new system allows certain functions of Moodle (eg string fetching) take advantage of different installed cache services (eg files, ram, memcached).

In future versions of Moodle we will continue expanding the number of Moodle functions that use MUC, which will continue improving performance, but you can already start using it to improve your site.

==General approach to performance testing==

Here is the general strategy you should be taking:

# Build a test environment that is as close to your real production instance as possible (eg hardware, software, networking, etc)
# Make sure to remove as many uncontrolled variables as you can from this environment (eg other services)
# Use a tool to place a realistic, but simulated and repeatable load upon you server. (eg jmeter or selenium).
# Decide on a way to measure performance of the server by capturing data (ram, load, time taken, etc)
# Run your load and measure a baseline performance result.
# Change one variable at a time, and re-run the load to see if performance gets better or worse. Repeat as necessary.
# When you discover settings that result in a consistent performance improvement, apply to your production site.

==How to use the caching settings==

Since Moodle 2.4, Moodle has provided a caching plugin framework to give administrators the ability to control where Moodle stores cached data. For most Moodle sites the default configuration should be sufficient and it is not necessary to change the configuration. For larger Moodle sites with multiple servers, administrators may wish to use memcached, mongodb or other systems to store cache data. The cache plugin screen provides administrators with the ability to configure what cache data is stored where.

=== Types of cache ===

Moodle uses three types of cache to store cached data:
* Request cache - The request cache is available for the duration of every page request. It is not shared between users and is used and cleared on every Moodle request.
* Session cache - The session cache is available through a users session in Moodle. It is not shared between users, but persists for a single user throughout their session (i.e. from when they logon til when they log off)
* Application cache - The application cache is a shared cache which is available for every request. It can be shared between users and the cached data can be kept indefinitely if required.

==== Cache types and multiple-server systems ====

If you have a system with multiple front-end web servers, the application cache must be shared between the servers. In other words, you cannot use fast local storage for the application cache, but must use shared storage or some other form of shared cache such as a shared memcache.

The same applies to session cache, unless you use a 'sticky sessions' mechanism to ensure that within a session, users always access the same front-end server.

===Installed cache stores===

This section of the administrator screen displays cache plugins which are installed on the system. It lists what the capabilities of each plugin, what type of cache they provide and provides allows a cache store to be added to the system.

===Configured store instances===

This section of the administrator screen displays cache stores which have been added to the system. It gives the ability to change the cache configuration and purge the cached data.

===Cache lock instances===

Moodle supports different mechanisms for 'locking' access to the various cache stores. At present there is only one option and it is not used, so it can safely be ignored.

===Known cache definitions===

Known cache definitions displays the caches which are in use by Moodle. Each item is an area of Moodle which is using caching. It gives the administrator the ability to configure an individual area of Moodle to use a different cache backend. For example, an administrator of a Moodle cluster may choose to make language string definitions be cached on a dedicated memcached server by using the memcached cache backend.

==Stores used when no mapping is present==

This section displays the default cache stores which should be used by Moodle for each type of Moodle cache. If a mapping for a cache definition does not exist then this default store will be used instead.

==Other performance testing==

Two links that might be useful to anyone considering testing performance on their own servers:

* [http://www.iteachwithmoodle.com/2012/10/12/moodle-performance-testing-how-much-more-horsepower-do-each-new-versions-of-moodle-require/ Moodle performance testing: how much more horsepower do each new versions of Moodle require?]
* [http://www.iteachwithmoodle.com/2012/10/11/how-to-stress-test-your-moodle-server-using-loadstorm/ How to load test your Moodle server using Loadstorm]

==See also==

* Using Moodle [https://moodle.org/mod/forum/discuss.php?d=217195 MUC is here, now what?] forum discussion

Developer documentation:
* [[:dev:The Moodle Universal Cache (MUC)]]
* [[:dev:Cache API]]
* [[:dev:Cache API - Quick reference]]

[[de:Caching]]

error/repository/instancenotsaved

2012-10-08T11:58:08Z

Quen: Created page with "This message (which doesn't seem to have a translation) occurs if there is a problem when creating a repository. Depending on the repository type, there might be various possibl..."

This message (which doesn't seem to have a translation) occurs if there is a problem when creating a repository.

Depending on the repository type, there might be various possible causes for this error. I am not aware of any particular way to cause this error in a standard Moodle install.

At a technical level, this would occur if a repository plugin returns false from its 'create' function. If the error occurs inappropriately while developing a new repository plugin, this is the probable cause.

Media embedding

2012-08-10T10:14:12Z

Quen:

{{Working with media}}
==Embedding audio and video==
[[File:mp3 player.png|thumb|MP3 player]]
Audio and video may be embedded in a course in the following ways:

* As a [[File module settings|file resource]]
* As a [[URL module settings|URL resource]] with embed as the display option
* In a [[Lesson settings|lesson popup]]
* In any text area using the Moodle media button in the [[Text editor|text editor]] or simply by typing the URL of media file

The media file link is then replaced with an appropriate multimedia player which can play the resource.

==Enabling media embedding==

To enable the embedding of media files, an admin must enable

# Appropriate media players (see below)
# The [[Multimedia plugins filter]] - unless you only want to allow embedding in File, URL and Lesson modules.

==Site administration settings==
{{New features}}An administrator can enable selected media players in ''Settings > Site administration > Appearance > Media embedding''.

===Available players===
* YouTube (displays videos hosted on youtube)
* Vimeo (displays videos hosted on vimeo)
* .mp3 - MPEG Audio Stream, Layer III
* .flv - Flash video
* .f4v - Flash video
* .swf - Macromedia Flash animation File (Adobe, Inc.)
:'''Note:''' Only used in trusted texts as it has potential security issues
* .ogg - HTML 5 audio
* .acc - HTML 5 audio
* .mp3 - HTML 5 audio
* .webm - HTML 5 video
* .m4v - HTML 5 video
* .ogv - HTML 5 video

===Legacy media players===
The following legacy media player formats are also available but not recommended for general usage:
* .mov - QuickTime player (requires QuickTime player or [http://en.wikipedia.org/wiki/Codec codec])
* .mp4 - QuickTime player (requires QuickTime player or codec)
* .m4a - QuickTime player (requires QuickTime player or codec)
* .mpg - MPEG animation - QuickTime player (requires QuickTime player or codec)
* .wmv - Windows media player (Microsoft)-not guaranteed to work in browsers other than IE and non-Windows systems
* .avi - Windows media player - not guaranteed to work in browsers other than IE and non-Windows systems

==See also==

* [[:dev:Media embedding]] developer documentation including information on how to change the size of the media player

[[Category:Site administration]]

[[de:Einbetten von Medien]]

mod/forumng/editpost

2012-02-28T15:46:28Z

Quen:

The ForumNG edit post form (used mainly for starting discussions) is quite similar to the equivalent post in the [[mod/forum/view|standard forum]].

This article is a stub. We would welcome improvements to ForumNG documentation, so please edit and make it better.

mod/forumng/editpost

2012-02-28T15:40:54Z

Quen: Created page with "The ForumNG edit post form (used mainly for starting discussions) is quite similar to the forum edit post form. This article is a stub. We would welcome i..."

The ForumNG edit post form (used mainly for starting discussions) is quite similar to the [[mod/forum/editpost|forum edit post form]].

This article is a stub. We would welcome improvements to ForumNG documentation, so please edit and make it better.

mod/forumng/discuss

2012-02-28T15:40:18Z

Quen: Created page with "The ForumNG discussion page is quite similar to the forum discussion page. This article is a stub. We would welcome improvements to ForumNG documentation, ..."

The ForumNG discussion page is quite similar to the [[mod/forum/discuss|forum discussion page]].

This article is a stub. We would welcome improvements to ForumNG documentation, so please edit and make it better.

mod/forumng/view

2012-02-28T15:39:43Z

Quen: Created page with "The ForumNG view page is quite similar to the forum view page. This article is a stub. We would welcome improvements to ForumNG documentation, so please edit ..."

The ForumNG view page is quite similar to the [[mod/forum/view|forum view page]].

This article is a stub. We would welcome improvements to ForumNG documentation, so please edit and make it better.

Performance FAQ

2011-12-02T14:04:42Z

Quen: added lots of opinion dressed up as fact about performance metrics

{{Performance}}
==How do you define "concurrent users"?==
As has been repeatedly stressed in the [http://moodle.org/mod/forum/view.php?f=94 Hardware and performance] forum, the load on the server at a particular time depends on the number of concurrent users, not on the total number of users neither on the number of users logged-in. The term "concurrent users" is used to mean those users for whom the server is actively doing something. It may by processing a webpage written in PHP, querying the database or simply transferring a file. (see also Wikipedia [http://en.wikipedia.org/wiki/Concurrency_(computer_science) Concurrency])

=== Why is "concurrent users" not a useful metric? ===

When considering a new site or new hardware, this metric is not very useful because you have no idea how many 'concurrent users' (a better term might be 'concurrent requests') you will have.

For example, if you have 10,000 registered users and you estimate that, during times of peak load, about 1,000 of those users will be using the system, there is no easy way to obtain the number of 'concurrent users'.

* It depends on what the users are doing (if they are contributing to a forum they will make fairly frequent requests but with long pauses to write posts; if they are downloading a PDF they will only make a single request but it will take a long time; if they are doing a quiz they will make very frequent requests).

* It also depends on system performance. If your system can serve a typical page in 0.1 seconds then if you have 10 people making a request within a second this is an average of 1 concurrent user. If your system takes 1 second to serve a page then the same usage pattern results in an average of 10 concurrent users.

In addition, the number of concurrent users is not a very accurate measure of demand because a "concurrent user" may be downloading a large file, which takes time to transfer based on the speed of their network connection. While this does place a demand on the server, a server may well be able to cope easily with sending out 10 large PDF files to 10 concurrent users with slow network connections, whereas it might struggle if 10 users were continuously making separate PHP requests to a complex page such as quiz.

=== What would be a better metric? ===

Peak requests per second (either from web logs, mdl_log lines, or similar) is probably a better way to roughly estimate demand on the server - but it is still very difficult to work this out for a new server with unknown usage patterns.

==How do I benchmark a Moodle-site?==
You can of course benchmark parts of the system separately: the hardware as seen by the operating system (eg. CPU, disk access), web server performance, database server performance, execution on PHP operations, etc. For further details see [[Performance#Obtain_a_baseline_benchmark]].

But there is no easy formula to deduce the maximum number of concurrent users from those results. There is a PHP-script, the [http://moodle.org/mod/forum/discuss.php?d=57028 Performance perspectives - a little script], circulating amoung the Moodle-community which calculates a ballpark figure. The current version is attached to [http://moodle.org/mod/forum/discuss.php?d=57028&parent=772267|the posting on 25. March 2011].

Warning: Note that running this script on a production server may have unwanted side-effects. You are strongly adviced to run it on a test-site.

==What are PHP-accelerators?==
See Wikipedia [http://en.wikipedia.org/wiki/PHP_accelerator PHP accelerator].

Available software are documented under [[Performance#PHP_performance]].

You find some user suggestions here [http://moodle.org/mod/forum/discuss.php?d=168965 Update on PHP-accelerators].

==How do I cluster Moodle?==

See [[Performance#Scalability]]

[[Moodle_Clusters]]

==How do I replicate Moodle?==

[[Mirroring_Moodle]]

[http://moodle.org/mod/forum/discuss.php?d=173408&parent=760514 How to Replicate MOODLE ??!!]

==My site is very slow, what should I do?==

First find out "how slow". (The theme-trick here).

The next question is, whether the performance is normal or something malfunctions. There are many things which can malfunction:
* hardware
* crashed filesystems, specially network filesystems
* memory leaks or other crashes in the system
* bug in Moodle
* corrupted database
* networking issues (DNS, firewalls, ...)

Or your performance could be "normal" under the given circumstances:
* Are you on a dedicated server or a shared (virtual) server?
* How much RAM, processing power do you have?
* What is the software stack you use? (Unix or Windows, Apache or IIS, MySQL, PostgreSQL or SQL-Server, ...?)
* how many concurrent users can you support
* what modules/activities you use? Check [[Performance#Performance of different Moodle modules]]

[[Performance#Obtain a baseline benchmark]] and compare it with the published figures.

==What are the requirements for N users?==

[http://moodle.org/mod/forum/discuss.php?d=111847 A moodle setup for 10K simultaneous users]

==How many users will my installation support?==

This is another way of asking the same question as above. Please move up.

==What is the best webserver?==

==Should I go for 64 bit or is 32 bit OK?==

==What hosting provider do you recommend?==
http://moodle.org/mod/forum/discuss.php?d=99405

== See also ==

Using Moodle forum discussions
* [http://moodle.org/mod/forum/search.php?notwords=Re:&id=5&subject=performance All performance related discussions]
* [http://moodle.org/mod/forum/search.php?notwords=Re:&id=5&forumid=33&&subject=performance Performance related discussions in the General Developer forum]

* [http://moodle.org/mod/forum/discuss.php?d=102978 1000 concurrent users]
* [http://moodle.org/mod/forum/discuss.php?d=103040 Tool to estimate server's maximum concurrent users]
* [http://moodle.org/mod/forum/discuss.php?d=144718 Handling Moodle database load - a solution!]

[[Category:FAQ]]

Performance FAQ

2011-12-02T14:01:19Z

Quen: /* How do you define "concurrent users"? */

{{Performance}}
==How do you define "concurrent users"?==
As has been repeatedly stressed in the [http://moodle.org/mod/forum/view.php?f=94 Hardware and performance] forum, the load on the server at a particular time depends on the number of concurrent users, not on the total number of users neither on the number of users logged-in. The term "concurrent users" is used to mean those users for whom the server is actively doing something. It may by processing a webpage written in PHP, querying the database or simply transferring a file. (see also Wikipedia [http://en.wikipedia.org/wiki/Concurrency_(computer_science) Concurrency])

=== Why is "concurrent users" not a useful metric? ===

When considering a new site or new hardware, this metric is not very useful because you have no idea how many 'concurrent users' (a better term might be 'concurrent requests') you will have.

For example, if you have 10,000 registered users and you estimate that, during times of peak load, about 1,000 of those users will be using the system, there is no easy way to obtain the number of 'concurrent users'.

* It depends on what the users are doing (if they are contributing to a forum they will make fairly frequent requests but with long pauses to write posts; if they are downloading a PDF they will only make a single request but it will take a long time; if they are doing a quiz they will make very frequent requests).

* It also depends on system performance. If your system can serve a typical page in 0.1 seconds then if you have 10 people making a request within a second this is an average of 1 concurrent user. If your system takes 1 second to serve a page then the same usage pattern results in an average of 10 concurrent users.

In addition, the number of concurrent users is not a very accurate measure of demand because a "concurrent user" may be downloading a large file, which takes time to transfer based on the speed of their network connection. While this does place a demand on the server, the demand of sitting there for 30 seconds transferring a large PDF file to somebody with a slow network connection is much less than the demand of handling, say, 30 one-second PHP requests over the same timeframe.

==How do I benchmark a Moodle-site?==
You can of course benchmark parts of the system separately: the hardware as seen by the operating system (eg. CPU, disk access), web server performance, database server performance, execution on PHP operations, etc. For further details see [[Performance#Obtain_a_baseline_benchmark]].

But there is no easy formula to deduce the maximum number of concurrent users from those results. There is a PHP-script, the [http://moodle.org/mod/forum/discuss.php?d=57028 Performance perspectives - a little script], circulating amoung the Moodle-community which calculates a ballpark figure. The current version is attached to [http://moodle.org/mod/forum/discuss.php?d=57028&parent=772267|the posting on 25. March 2011].

Warning: Note that running this script on a production server may have unwanted side-effects. You are strongly adviced to run it on a test-site.

==What are PHP-accelerators?==
See Wikipedia [http://en.wikipedia.org/wiki/PHP_accelerator PHP accelerator].

Available software are documented under [[Performance#PHP_performance]].

You find some user suggestions here [http://moodle.org/mod/forum/discuss.php?d=168965 Update on PHP-accelerators].

==How do I cluster Moodle?==

See [[Performance#Scalability]]

[[Moodle_Clusters]]

==How do I replicate Moodle?==

[[Mirroring_Moodle]]

[http://moodle.org/mod/forum/discuss.php?d=173408&parent=760514 How to Replicate MOODLE ??!!]

==My site is very slow, what should I do?==

First find out "how slow". (The theme-trick here).

The next question is, whether the performance is normal or something malfunctions. There are many things which can malfunction:
* hardware
* crashed filesystems, specially network filesystems
* memory leaks or other crashes in the system
* bug in Moodle
* corrupted database
* networking issues (DNS, firewalls, ...)

Or your performance could be "normal" under the given circumstances:
* Are you on a dedicated server or a shared (virtual) server?
* How much RAM, processing power do you have?
* What is the software stack you use? (Unix or Windows, Apache or IIS, MySQL, PostgreSQL or SQL-Server, ...?)
* how many concurrent users can you support
* what modules/activities you use? Check [[Performance#Performance of different Moodle modules]]

[[Performance#Obtain a baseline benchmark]] and compare it with the published figures.

==What are the requirements for N users?==

[http://moodle.org/mod/forum/discuss.php?d=111847 A moodle setup for 10K simultaneous users]

==How many users will my installation support?==

This is another way of asking the same question as above. Please move up.

==What is the best webserver?==

==Should I go for 64 bit or is 32 bit OK?==

==What hosting provider do you recommend?==
http://moodle.org/mod/forum/discuss.php?d=99405

== See also ==

Using Moodle forum discussions
* [http://moodle.org/mod/forum/search.php?notwords=Re:&id=5&subject=performance All performance related discussions]
* [http://moodle.org/mod/forum/search.php?notwords=Re:&id=5&forumid=33&&subject=performance Performance related discussions in the General Developer forum]

* [http://moodle.org/mod/forum/discuss.php?d=102978 1000 concurrent users]
* [http://moodle.org/mod/forum/discuss.php?d=103040 Tool to estimate server's maximum concurrent users]
* [http://moodle.org/mod/forum/discuss.php?d=144718 Handling Moodle database load - a solution!]

[[Category:FAQ]]

Development:Commit cheat sheet

2011-04-14T10:37:35Z

Quen:

You can consider this page as a list to check before you submit a patch for inclusion into Moodle.

== Split your work into a logical set of patches ==

Keep in mind that your commits will be reviewed before they are accepted. If the patch does one clear thing and does it well, the review process is fun. Git allows you to prepare patches on your branch into a sequence of logical steps. For example, when changing some API, divide the change into two steps. In the first commit, change the API. In the following commit, change all places that use the API.

== Provide clear commit messages ==

Consider the commit message as an email for the developer who would explore the change in the future. We recommend to follow common Git guidelines for formatting. Include the MDL issue number and eventually the area/component at the beginning of the subject line.

MDL-xxxxx code area: short description of the patch<br />
The subject line is followed by an empty line and then a paragraph or two of
a longer description follows. This longer description is useful for issues
with longer history of comments in the linked MDL so that it summarizes the
patch without the need to go through the whole discussion.<br />
Obviously, avoid messages like "as agreed in the chat" as they will become
useless after a relatively short time.

Most of Git tools are optimised for this format and they can display the log of commits best then.

== Names in the commit message ==

Retain the authorship of the patch. If the patch was submitted by someone else - for example a community member who published it in the tracker or in a forum - use the --author parameter. Make sure that your ''real'' name and contact email are recorded in patch. We use real names written in capital letters like "John Smith". Please do not use names like <strike>"john smith", "John S", "johnny7887"</strike>. If you use --author parameter, apply the same rules for the name of the author. See almost any Git tutorial on how to set your name and email in the global Git configuration.

== Provide clear and operational instructions to test your patch ==

In the PULL request, please describe how the change can be tested. Please avoid vague phrases like "Make sure there is no regression in the core" or "Test all places where XXX is used". Also, try to avoid requiring resources that are really difficult to gather, if possible - as in "Use production data from a server with 100.000+ students".

In most cases, the instructions for testers should go into the PULL request to make the tester's life easier. This means you will need to copy and paste them into every PULL request (if there are multiple PULL requests for different branches, or if your first PULL request gets rejected).

If the instructions are elsewhere (for example they were provided by the reporter in the linked MDL as a part of steps to reproduce), you could inform testers in the PULL request where they can find them. However it is preferable to copy/paste the instructions into each PULL.

It helps if you state your estimation of the testing difficulty so that testers can pick issues for them:

* ''Easy'' (average community member should be able to test it) - can be tested pretty easily via the web interface only at a public test site
* ''Moderate'' (knowledgeable administrator should be able to test it) - requires local installation, for example to test some 1.9 -> 2.0 upgrade steps or some non-standard environment (for example MNet features, specific platform etc)
* ''Hard'' (development skills are required to test it) - for example may require data hacking at SQL level to simulate data corruption or modifying the code to reproduce the problem

Example of instructions for testers:

INSTRUCTIONS FOR TESTING (difficulty: easy, requires teacher access to a course)<br />
1. Log in as a teacher and go to a course (you can use some of yours or restore the attached .mbz backup)
2. Turn editing mode on
3. TEST: Make sure that the control icons appear next to the activity titles
4. Turn editing mode off
5. TEST: Make sure that the control icons are not displayed now

== Introducing new strings ==

Firstly, think twice and try to think in a non-English language. Any string you introduce is supposed to be translated by translators who usually do it for free in their own time. Do not waste their time by using get_string() for debugging messages that are likely to almost never appear. It is warmly recommended to let Helen review your strings before you submit them. This way we can keep the terminology and the style consistent. When introducing new strings, keep them alphabetically sorted. Using a self-descriptive names of the string identifier and the placeholder properties helps the translators to guess the context. Compare the following

$string['grade'] = 'Grade {$a}';

with

$string['maxgradevalue'] = 'Grade {$a->value}';

In the first case, it is pretty difficult to guess whether the "Grade" in the string is a noun (as in "Grade 12/30") or a verb (as in "Grade submission"). In many languages, the translation depends on it. The second case is more self-descriptive as it indicates that the placeholder will contain a value.

See [[Development:Help strings]] if you are introducing a new help string.

== Include AMOS script in the commit if needed ==

If you change the identifier of a string or split a string into two forks, provide a script for AMOS in the commit message. Since Moodle 2.0, the translations are kept on separated branches again. The AMOS plugin at http://lang.moodle.org tracks the changes in string files and automatically records modifications, additions and removals of strings. Therefore strings can be re-worded freely on stable branches and should be removed from the master branch if they are not needed any more.

If you change the identifier of the string (that is the key in the $string array), move the string from one file to another or you are introducing a new string as a copy of some current one, you should provide instructions for AMOS so that the action can be applied in all language packs. That will save valuable translators' time. Instructions for AMOS are being put into the commit message of a commit that modifies the original English string files. The commit message containing such a script may look like this:

MDL-xxxxx code area: short description of the patch<br />
It is recommended to leave a blank line between the commit message and the
script block.<br />
AMOS BEGIN
MOV [configfoobar,core_admin],[foobar_desc,core_admin]
CPY [submission,mod_assignment],[submission,mod_workshop]
AMOS END

See [[Development:Languages/AMOS#AMOS_script]] for more details of the syntax. See [http://git.moodle.org/gw?p=moodle.git&a=search&h=HEAD&st=commit&s=AMOS+BEGIN the log history] real examples of usage.

== Main version changes ==

If your commit requires a change to the main version number in version.php (and corresponding upgrade in lib/db/upgrade.php), you should increment that version number by .01, and let integrators deal with merge conflicts (for example if multiple people that week submit several .01 updates).

(Note there may be policies about avoiding the type of changes which require version.php updates, especially in stable branches.)

Development talk:Anonymous Users

2011-04-14T09:56:51Z

Quen: /* Forum table changes */

Are you sure it should be a user_alias_course table? The other option would be to do user_alias_context, which would be more flexible. Not sure if you need the flexibility, but increasingly in Moodle things are being linked to contexts.

Good point Tim. I played with the code and it actually is a lot easier than I imagined, mostly thanks to seeing the code you did for the filters. Overall I think it does give maximum fexibility so will approach it this way. --[[User:Shane Elliott|Shane Elliott]] 09:41, 1 May 2010 (UTC)

== Forum table changes ==

Spec doesn't seem to mention the necessary changes to forum tables; forum_posts needs an 'anonymous' field, at least.

Also I didn't really understand how to implement support for this in a module. For instance I guess I could define FEATURE_ANONYMOUS in my module _supports function and then it would automatically add the option to the mod_form for me, but it doesn't say that.

Then should the anonymous option for that module be stored in course_modules? (I see the desire to do it with context but there is no standard UI for editing things in different contexts and we can't support it across all modules without module changes so there is no point offering it at course level... or is there...)

If it's not in course_modules then as we are going to need it in lots of places potentially, should it be cached in modinfo?

If you don't have permission to view anonymous, but you do have permission to view the 'forum posts' tab on the user profile, then this tab needs to not include anonymous messages...

I think this is probably a lot more difficult (to do properly) than what's already included in the spec. :(

You could code it a bit more easily as a feature specific to forum, though.

[[User:sam marshall|sam marshall]] 17:56, 14 April 2011 (WST)

Development talk:Anonymous Users

2011-04-14T09:56:37Z

Quen: /* Forum table changes */ new section

Development:Commit cheat sheet

2011-04-07T10:15:40Z

Quen: /* Provide clear and operational instructions to test your patch */

Development:Commit cheat sheet

2011-04-07T10:13:56Z

Quen: /* Provide clear and operational instructions to test your patch */

You can consider this page as a list to check before you submit a patch for inclusion into Moodle.

== Split your work into a logical set of patches ==

Keep in mind that your commits will be reviewed before they are accepted. If the patch does one clear thing and does it well, the review process is fun. Git allows you to prepare patches on your branch into a sequence of logical steps. For example, when changing some API, divide the change into two steps. In the first commit, change the API. In the following commit, change all places that use the API.

== Provide clear commit messages ==

Consider the commit message as an email for the developer who would explore the change in the future. We recommend to follow common Git guidelines for formatting. Include the MDL issue number and eventually the area/component at the beginning of the subject line.

MDL-xxxxx code area: short description of the patch<br />
The subject line is followed by an empty line and then a paragraph or two of
a longer description follows. This longer description is useful for issues
with longer history of comments in the linked MDL so that it summarizes the
patch without the need to go through the whole discussion.<br />
Obviously, avoid messages like "as agreed in the chat" as they will become
useless after a relatively short time.

Most of Git tools are optimised for this format and they can display the log of commits best then.

== Names in the commit message ==

Retain the authorship of the patch. If the patch was submitted by someone else - for example a community member who published it in the tracker or in a forum - use the --author parameter. Make sure that your ''real'' name and contact email are recorded in patch. We use real names written in capital letters like "John Smith". Please do not use names like <strike>"john smith", "John S", "johnny7887"</strike>. If you use --author parameter, apply the same rules for the name of the author. See almost any Git tutorial on how to set your name and email in the global Git configuration.

== Provide clear and operational instructions to test your patch ==

In the PULL request, please describe how the change can be tested. Please avoid vague phrases like "Make sure there is no regression in the core" or "Test all places where XXX is used". Also, try to avoid requiring resources that are really difficult to gather, if possible - as in "Use production data from a server with 100.000+ students".

In most cases, the instructions for testers should go into the PULL request to make the tester's life easier. This means you will need to copy and paste them into every PULL request (if there are multiple PULL requests for different branches, or if your first PULL request gets rejected). If these instructions are in the MDL

If the instructions are elsewhere (for example they were provided by the reported in the linked MDL as a part of steps to reproduce), please inform testers in the PULL request where they can find them. However it is preferable to copy/paste the instructions into each PULL.

It helps if you state your estimation of the testing difficulty so that testers can pick issues for them:

* ''Easy'' (average community member should be able to test it) - can be tested pretty easily via the web interface only at a public test site
* ''Moderate'' (knowledgeable administrator should be able to test it) - requires local installation, for example to test some 1.9 -> 2.0 upgrade steps or some non-standard environment (for example MNet features, specific platform etc)
* ''Hard'' (development skills are required to test it) - for example may require data hacking at SQL level to simulate data corruption or modifying the code to reproduce the problem

Example of instructions for testers:

INSTRUCTIONS FOR TESTING (difficulty: easy, requires teacher access to a course)<br />
1. Log in as a teacher and go to a course (you can use some of yours or restore the attached .mbz backup)
2. Turn editing mode on
3. TEST: Make sure that the control icons appear next to the activity titles
4. Turn editing mode off
5. TEST: Make sure that the control icons are not displayed now

== Introducing new strings ==

Firstly, think twice and try to think in a non-English language. Any string you introduce is supposed to be translated by translators who usually do it for free in their own time. Do not waste their time by using get_string() for debugging messages that are likely to almost never appear. It is warmly recommended to let Helen review your strings before you submit them. This way we can keep the terminology and the style consistent. When introducing new strings, keep them alphabetically sorted. Using a self-descriptive names of the string identifier and the placeholder properties helps the translators to guess the context. Compare the following

$string['grade'] = 'Grade {$a}';

with

$string['maxgradevalue'] = 'Grade {$a->value}';

In the first case, it is pretty difficult to guess whether the "Grade" in the string is a noun (as in "Grade 12/30") or a verb (as in "Grade submission"). In many languages, the translation depends on it. The second case is more self-descriptive as it indicates that the placeholder will contain a value.

See [[Development:Help strings]] if you are introducing a new help string.

== Include AMOS script in the commit if needed ==

If you change the identifier of a string or split a string into two forks, provide a script for AMOS in the commit message. Since Moodle 2.0, the translations are kept on separated branches again. The AMOS plugin at http://lang.moodle.org tracks the changes in string files and automatically records modifications, additions and removals of strings. Therefore strings can be re-worded freely on stable branches and should be removed from the master branch if they are not needed any more.

If you change the identifier of the string (that is the key in the $string array), move the string from one file to another or you are introducing a new string as a copy of some current one, you should provide instructions for AMOS so that the action can be applied in all language packs. That will save valuable translators' time. Instructions for AMOS are being put into the commit message of a commit that modifies the original English string files. The commit message containing such a script may look like this:

MDL-xxxxx code area: short description of the patch<br />
It is recommended to leave a blank line between the commit message and the
script block.<br />
AMOS BEGIN
MOV [configfoobar,core_admin],[foobar_desc,core_admin]
CPY [submission,mod_assignment],[submission,mod_workshop]
AMOS END

See [[Development:Languages/AMOS#AMOS_script]] for more details of the syntax. See [http://git.moodle.org/gw?p=moodle.git&a=search&h=HEAD&st=commit&s=AMOS+BEGIN the log history] real examples of usage.

Development:Restore 2.0 for developers

2011-04-04T10:21:39Z

Quen: /* Automatically triggering restore in code */

Installing Moodle from Git repository

2011-03-31T12:48:52Z

Quen: /* Installing other versions */

'''This page is a work in progress'''
== Command line (all platforms) ==

Using the cd command, move to the directory that you wish to install Moodle inside. The Moodle code will be placed in a subdirectory of the directory you're currently in. For example, if you are in /tmp when you run the command, Moodle will be installed in /tmp/moodle.

Clone the offical Moodle repository via git, taking the 2.0 stable branch, and placing it into a subdirectory called moodle.

git clone -b MOODLE_20_STABLE git://git.moodle.org/moodle.git moodle

If you have firewall issues with the git protocol, the above may not work, in which case you can try cloning the official github repository via http

git clone -b MOODLE_20_STABLE https://github.com/moodle/moodle.git moodle

Whichever command works it should display a result like the following. Installing will probably take around ten minutes.

Initialized empty Git repository in ~/moodle/.git/
remote: Counting objects: 448351, done.
remote: Compressing objects: 100% (103262/103262), done.
remote: Total 448351 (delta 336929), reused 446784 (delta 335924)
Receiving objects: 100% (448351/448351), 128.54 MiB | 10.94 MiB/s, done.
Resolving deltas: 100% (336929/336929), done.

Move in to the new moodle directory that you just created.

cd moodle

From here, you can edit config.php and install as per the [[Installing_Moodle#Setting-up_your_web_server|Installation Instructions]]

Upgrading to the latest Moodle 2.0 version is now one simple command. Change into the moodle directory and then run:

git pull origin MOODLE_20_STABLE

== Installing other versions ==

You can install another version by replacing MOODLE_20_STABLE with e.g. MOODLE_19_STABLE. If you want the latest unfinished development version, use 'master' (note lower-case) instead of MOODLE_20_STABLE.

Installing Moodle from Git repository

2011-03-31T12:48:20Z

Quen: /* Installing other versions */

'''This page is a work in progress'''
== Command line (all platforms) ==

Using the cd command, move to the directory that you wish to install Moodle inside. The Moodle code will be placed in a subdirectory of the directory you're currently in. For example, if you are in /tmp when you run the command, Moodle will be installed in /tmp/moodle.

Clone the offical Moodle repository via git, taking the 2.0 stable branch, and placing it into a subdirectory called moodle.

git clone -b MOODLE_20_STABLE git://git.moodle.org/moodle.git moodle

If you have firewall issues with the git protocol, the above may not work, in which case you can try cloning the official github repository via http

git clone -b MOODLE_20_STABLE https://github.com/moodle/moodle.git moodle

Whichever command works it should display a result like the following. Installing will probably take around ten minutes.

Initialized empty Git repository in ~/moodle/.git/
remote: Counting objects: 448351, done.
remote: Compressing objects: 100% (103262/103262), done.
remote: Total 448351 (delta 336929), reused 446784 (delta 335924)
Receiving objects: 100% (448351/448351), 128.54 MiB | 10.94 MiB/s, done.
Resolving deltas: 100% (336929/336929), done.

Move in to the new moodle directory that you just created.

cd moodle

From here, you can edit config.php and install as per the [[Installing_Moodle#Setting-up_your_web_server|Installation Instructions]]

Upgrading to the latest Moodle 2.0 version is now one simple command. Change into the moodle directory and then run:

git pull origin MOODLE_20_STABLE

== Installing other versions ==

You can install another version by replacing MOODLE_20_STABLE with e.g. MOODLE_19_STABLE. If you want the latest development version, use 'master' (note lower-case) instead of MOODLE_20_STABLE.

Installing Moodle from Git repository

2011-03-31T12:46:24Z

Quen:

'''This page is a work in progress'''
== Command line (all platforms) ==

Using the cd command, move to the directory that you wish to install Moodle inside. The Moodle code will be placed in a subdirectory of the directory you're currently in. For example, if you are in /tmp when you run the command, Moodle will be installed in /tmp/moodle.

Clone the offical Moodle repository via git, taking the 2.0 stable branch, and placing it into a subdirectory called moodle.

git clone -b MOODLE_20_STABLE git://git.moodle.org/moodle.git moodle

If you have firewall issues with the git protocol, the above may not work, in which case you can try cloning the official github repository via http

git clone -b MOODLE_20_STABLE https://github.com/moodle/moodle.git moodle

Whichever command works it should display a result like the following. Installing will probably take around ten minutes.

Initialized empty Git repository in ~/moodle/.git/
remote: Counting objects: 448351, done.
remote: Compressing objects: 100% (103262/103262), done.
remote: Total 448351 (delta 336929), reused 446784 (delta 335924)
Receiving objects: 100% (448351/448351), 128.54 MiB | 10.94 MiB/s, done.
Resolving deltas: 100% (336929/336929), done.

Move in to the new moodle directory that you just created.

cd moodle

From here, you can edit config.php and install as per the [[Installing_Moodle#Setting-up_your_web_server|Installation Instructions]]

Upgrading to the latest Moodle 2.0 version is now one simple command. Change into the moodle directory and then run:

git pull origin MOODLE_20_STABLE

== Installing other versions ==

You can install another version by replacing MOODLE_20 with e.g. MOODLE_19. If you want the latest development version, use 'master' (note lower-case) instead of MOODLE_20.

Development:Restore 2.0 for developers

2011-03-21T14:07:38Z

Quen: /* Automatically triggering restore in code */

Development:Restore 2.0 for developers

2011-03-21T14:06:51Z

Quen: /* Automatically triggering restore in code */

Development:Restore 2.0 for developers

2011-03-21T14:06:24Z

Quen:

Development:Themes 2.0

2011-03-15T13:15:06Z

Quen: /* Unobvious Things */

{{Template:Themes}}{{Moodle 2.0}}Welcome to the new world of themes within Moodle 2.0!

This document explains how themes work in Moodle and is intended to help you create or modify most themes for Moodle 2.0.

==Introduction==

Moodle themes are responsible for much of the "look" of a Moodle site. They provide the CSS for colours, layouts, fonts and so on, and can also change the structural XHTML code below that.

A theme can either contain all the definitions (completely stand alone) or it can extend an existing theme with one or more customizations.

Most theme developers use the second method and simply add a few new CSS or layout definitions to their new theme. If a definition or element is not found in the new theme, it looks to the "parent" (or up the hierarchy of themes) to find one. It an easy way to achieve just about any look you want for a theme.

==What's new in 2.0==

The theme system was completely redesigned in Moodle 2.0. Known issues have been addressed and new features have been added to meet community requests.

Unfortunately it was not possible to maintain backward compatibility, so all Moodle 1.x themes need to be recreated for Moodle 2.0.

Major changes include:
* Clearer and more consistent CSS classes and IDs throughout all pages in Moodle
* Introduction of layout files (templates) describing overall layout HTML for many different types of pages in Moodle.
* Introduction of renderers, which produce the smaller "parts" of a HTML page. Advanced themes can choose to override these too if they choose.
* Introduction of standard methods for adding Javascript to themes.
* Easier control over icons and images in Moodle.
* The old "standard" theme has been split into two themes:
**'''base''' - contains absolutely basic layout, and
**'''standard''' - which adds CSS to the base theme to make it look like the old standard theme.
* Performance tuning: In normal production mode CSS files are combined into a single optimised file, and both CSS and JavaScript files are minimised to ensure there are no wasted connections or traffic. Files are heavily cached, but also versioned, so that users never need to clear their caches.

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

===Files and folders===
A theme's files are placed in a folder with under moodle/theme folder and have subfolders. They are laid out like this:

{| class="nicetable"
|-
! Directory
! File
! Description
|-
|
| /config.php
| Contains all of the configuration and definitions for each theme
|-
|
| /lib.php
| Contains speciality classes and functions that are used by theme
|-
|
| /renderers.php
| Contains any custom renderers for the theme.
|-
|
| /settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /javascript/
|
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
|
| Contains the layout files for the theme.
|-
| /pix/
|
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix
| /favicon.ico
| The favicon to display for this theme.
|-
| /pix
| /screenshot.jpg
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /style
|
| Default location for CSS files.
|-
|
|/*.css
|CSS files the theme requires
|}

There are also several other places that stylesheets can be included from (see the CSS how and why section below).

==Theme options==
All theme options are set within the config.php file for the theme. The settings that are most used are: parents, sheets, layouts, and javascripts. Have a look at the '''[[#theme_options_table|theme options table]]''' for a complete list of theme options which include lesser used specialised or advanced settings.

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

$THEME->parents = array(
'base'
);

$THEME->sheets = array(
'admin',
'blocks',
'calendar',
'course',
'grade',
'message',
'question',
'user'
);

$THEME->layouts = array(
'base' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array(),
),
'standard' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
)
//.......
);

$THEME->javascripts_footer = array(
'navigation'
);
</code>

===Basic theme example settings explained===
First up you will notice everything is added to $THEME. This is the theme's configuration object, it is created by Moodle using default settings and is then updated by whatever settings you add to it.

The first setting, $THEME->name is the theme's name. This should simply be whatever your theme's name is, most likely whatever you named your theme directory.

$THEME->parents defines the themes that the theme will extend. In this case it is extending only the base theme.

After this is the $THEME->sheets array containing the names of the CSS stylesheets to include for this theme. Note that it is just the name of the stylesheet and does not contain the directory or the file extension. Moodle assumes that the theme's stylesheets will be located in the styles directory of the theme and have .css as an extension.

Next we see the $THEME->layouts definition. In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

The final setting is to include a JavaScript file, as $THEME->javascripts_footer. Much like stylesheets, you only need to provide the files name. Moodle will assume it is in your themes JavaScript directory and be a .js file.

'''''Note''''': When you first begin writing themes, make sure you take a look at the configuration files of the other themes that get shipped with Moodle. You will get a good picture of how everything works, and what is going on in a theme, simply by reading it and taking notice of what it is including or excluding.

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\styles\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

New theme developers should note that the order in which CSS files are found and included creates a hierarchy. This order ensures that the rules, within a theme's style sheets, take precedence over identical rules in other files that may have been introduced before. This can both extend another files definitions (see parent array in the config file) and also ensures that the current theme's CSS rules/definitions have the last say.

There are other locations that can be used (although very rarely) to include CSS in a page. A developer of a php file can manually specify a stylesheet from anywhere within Moodle, like the database. Usually, if code is doing this, it is because there is a non-theme config or plugin setting that contains information requires special CSS information. As a theme designer you should be aware of, but not have to worry about, these locations of CSS files. Here are some examples:

; {pluginpath}\styles.css e.g. \block\blockname\styles.css or \mod\modname\styles.css : Every plugin can have its own styles.css file. This file should only contain the required CSS rules for the module and should not add anything to the look of the plugin such as colours, font sizes, or margins other than those that are truly required.<br />Theme specific styles for a plugin should be located within the themes styles directory.
; {pluginpath}\styles_themename.css : This should only ever be used by plugin developers. It allows them to write CSS that is designed for a specific theme without having to make changes to that theme. You will notice that this is never used within Moodle and is designed to be used only by contributed code.

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the themes styles directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

First is the pagelayout.css file. This contains the CSS required to give the layouts their look and feel. It doesn't contain any rules that affect the content generated by Moodle.

Next is the core.css file. If you open up core you will notice that it contains all manner of general (usually simple) rules that don't relate to a specific section of Moodle but to Moodle as a whole.

There can also be rules that relate to specific sections. However, this is done only when there are only a handful of rules for that section. These small clusters of rules are grouped together and separated by comments identifying for which section each relates.

Finally there are all the other CSS files, you will notice that there is a file for each section of Moodle that has a significant collection of rules.

:For those who are familiar with Moodle 1.9 theme's, this organisation will be a big change. In 1.9, CSS was organised by its nature (for example: colours, layout, other).

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is an incredibly important.

Due to performance requirements and browser limitations, all of the CSS files are combined into a single CSS file that gets included every time. This means that rules need to be written in such a way as to minimise the chances of a collision leading to unwanted styles being applied. Whilst writing good CSS is something most designers strive for we have implemented several new body classes and put more emphasis on developers for using classes more appropriately.

====The body tag====
As of Moodle 2.0 the ID tag that gets applied to the body will always be a representation of the URI. For example if you are looking at a forum posting and the URI is '/mod/forum/view.php' then the body tags ID will be '#page-mod-forum-view'.

As well as the body's ID attribute the URI is also exploded to form several CSS classes that get added to the body tag, so in the above example '/mod/forum/view' you would end up with the following classes being added to the body tag '.path-mod', '.path-mod-forum'. Note that '.path-mod-forum-view' is not added as a class, this is intentionally left out to lessen confusion and duplication as rules can relate directly to the page by using the ID and do not require the final class.

The body ID and body classes described above will form the bread and butter for many of the CSS rules you will need to write for your theme, however there are also several other very handy classes that get added to the body tag that will be beneficial to you once you start your journey down the rabbit hole that is themeing. Some of the more interesting classes are listed below.

* If JavaScript is enabled then 'jsenabled' will be added as a class to the body tag allowing you to style based on JavaScript being enabled or not.
* Either 'dir-rtl' or 'dir-ltr' will be added to the body as a class depending on the direction of the language pack: rtl = right to left, ltr = left to right. This allows you to determine your text-alignment based on language if required.
* A class will be added to represent the language pack currently in use, by default en_utf8 is used by Moodle and will result in the class 'lang-en_utf8' being added to the body tag.
* The wwwroot for Moodle will also be converted to a class and added to the body tag allowing you to stylise your theme based on the URL through which it was reached. e.g. http://sam.moodle.local/moodle/ will become '.sam-moodle-local—moodle'
* If the current user is not logged then '.notloggedin' will be added to the body tag.

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====
The best use of body ids and classes and writing selectors will reduce problems.

There are many specific classes used within Moodle. We try to put them everywhere where anyone may want to apply their own styles. It is important to recognise that no one developer can be aware of the all of the class names that have been used all throughout Moodle, let alone within all of the different contributed bits and pieces available for Moodle. It is up to the theme developer to write good rules and minimise the chances of a collision between rules because in this case good CSS is FAR more effective.

When starting to write rules make sure that you have a good understanding of where you want those rules to be applied, it is a good idea to make the most of the body classes mentioned above.
If you want to write a rule for a specific page make use of the body tag's ID, e.g.:

<code css>#page-mod-forum-view .forumpost {border:1px solid orange;)</code>

If you want to write a rule that will be applied all throughout the forum.:

<code css>.path-mod-forum .forumpost {border:1px solid orange;}</code>

The other very important thing to take into consideration is the structure leading up to the tag you want to style. Browsers apply conflicting styles with priority on the more specific selectors. It can be very beneficial to keep this in mind and write full selectors that rely on the structure of the tags leading to the tag you wish to style.

By making use of body id's and classes and writing selectors to take into account the leading structure you can greatly minimise the chance of a collision both with Moodle now and in the future.

==Layouts==
All themes are required to define the layouts they wish to be responsible for as well as create; however, many layout files are required by those layouts. If the theme is overriding another theme then it is a case of deciding which layouts this new theme should override. If the theme is a completely fresh start then you will need to define a layout for each of the different possibilities. For both situations these layouts should be defined within config.php.

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

So layouts... as mentioned earlier layouts are defined in config.php within $THEME->layouts. The following is an example of one such layout definition:
<code php>
$THEME->layouts = array(
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'theme' => 'base',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
)
)
</code>
The first thing Moodle looks at is the name of the layout, in this case it is `standard` (the array key in PHP), it then looks at the settings for the layout, this is the theme, file, regions, and default region. There are also a couple of other options that can be set by a layout.

; theme : is the theme the layout file exists in. That's right you can make use of layouts from other installed themes. ''Optional''
; file : is the name of the layout file this layout wants to use. ''Required''
; regions : is the different block regions (places you can put blocks) within the theme. ''Required''
; defaultregion : is the default location when adding new blocks. '''Required if regions is non-empty, otherwise optional'''
; options : an array of layout specific options described in detail below. '''Optional'''

The '''theme''' is optional. Normally the the layout file is looked for in the current theme, or, if it is not there, in the parent theme. However, you can use a layout file from any other theme by giving the theme name here.

You can define whatever regions you like. You just need to pick an name for each one. Most themes just use one or both of '''side_pre''' and '''side_post''', which is like 'left side' and 'right side', except in right to left languages, when they are reversed. If you say in config.php that your the layout provides regions called 'fred' and 'barney', then you must call $OUTPUT->blocks_for_region('fred') and $OUTPUT->blocks_for_region('barney') somewhere in the layout file.

The final setting '''options''' is a special case that only needs to be set if you want to make use of it. This setting allows the theme designer to specify special options that they would like to create that can be later accessed within the layout file. This allows the theme to make design decisions during the definition and react upon those decisions in what ever layout file is being used.

One such place this has been used is infact within the base theme. If you take a look first at theme/base/config.php you will notice that several layouts specify options '''nonavbar''' and '''nofooter''' which can both be set to either true or false. Then if we take a look at theme/base/layout/general.php you will spot lines like the following:
<code php>
<?php
$hasnavbar = (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar());
$hasfooter = (empty($PAGE->layout_options['nofooter']));
?>
............
<?php if ($hasnavbar) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
What you are seeing here is the use of those settings from the layout within the layout file. In this case it is being used to toggle the display of the navigation bar and page footer.

==Layout files==
A layout file is a file that contains the core HTML structure for a layout including the header, footer, content and block regions.
For those of you who are familiar with themes in Moodle 1.9 this is simply header.html and footer.html combined.
Of course it is not all HTML, there are bits of HTML and content that Moodle needs to put into the page, within each layout file this will be done by a couple of VERY simple PHP calls to get bits and pieces including content.

The following is a very simple layout file to illustrate the different bits that make it up:
<code php>
<?php echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
<body id="<?php echo $PAGE->bodyid ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<table id="page">
<tr>
<td colspan="3">
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?></div>
</td>
</tr>
<tr>
<td>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</td>
<td>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</td>
<td>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</td>
</tr>
<tr>
<td colspan="3">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</td>
</tr>
</table>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

Lets assume you know a enough HTML to understand the basic structure above, what you probably don't understand are the PHP calls so lets look at them.
<code php>
<?php echo $OUTPUT->doctype() ?>
</code>
This occurs at the VERY top of the page, it must be the first bit of output and is responsible for adding the (X)HTML document type definition to the page. This of course is determined by the settings of the site and is one of the things that the theme designer has no control over.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we have started writing the opening html tag and have asked Moodle to give us the HTML attributes that should be applied to it. This again is determined by several settings within the actual HTML install.

<code php>
<?php echo $PAGE->title ?>
</code>
This gets us the title for the page.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
This very important call gets us the standard head HTML that needs to be within the HEAD tag of the page. This is where CSS and JavaScript requirements for the top of the page will be output as well as any special script or style tags.

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
</code>
Much like the html tag above we have started writing the body tag and have asked for Moodle to get us the desired ID and classes that should be applied to it.

<code php>
<h1 class="headermain"><?php echo $PAGE->heading; ?></h1>
<div class="headermenu"><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?></div>
</code>
Here we are creating the header for the page. In this case we want the heading for the page, we want to display the login information which will be the current users username or a link to log in if they are not logged in, and we want the heading menu if there is one.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-pre''.

<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This is one of the most important calls within the file, it determines where the actual content for the page gets inserted.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-post''.

<code php>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</code>
This final bit of code gets the content for the footer of the page. It gets the login information which is the same as in the header, a home link, and the standard footer HTML which like the standard head HTML contains all of the script and style tags required by the page and requested to go in the footer.

'''''Note''''': Within Moodle 2.0 most of the JavaScript for the page will be included in the footer. This greatly helps reduce the loading time of the page.

When writing layout files think about the different layouts and how the HTML that each makes use of will differ. You will most likely find you do not need a different layout file for each layout, most likely you will be able to reuse the layout files you create across several layouts. You can of course make use of layout options as well to further reduce the number of layout files you need to produce.

Of course as mentioned above if you are customising an existing theme then you may not need to create any layouts or layout files at all.

'''$OUTPUT''' is an instance of the '''core_renderer''' class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the '''moodle_page''' class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes, some magic is going on, and the value you get is produced by calling a function. Also, you cannot change these values, they are read-only. However, you don't need to understand all that if you are just using these properties in your theme.)

==Making use of images==
Right at the start when listing the features of the new themes system one of the features mentioned was the ability to override any of the standard images within Moodle from within your theme. At this point we will look at both how to make use of your own images within your theme, and secondly how to override the images being used by Moodle.
So first up a bit about images within Moodle,

# Images you want to use within your theme '''need''' to be located within your theme's pix directory.
# You can use sub directories within the pix directory of your theme.
# Images used by Moodle's core are located within the pix directory of Moodle.
# Modules, blocks and other plugins should also store there images within a pix directory.

So making use of your own images first up. Lets assume you have added two image files to the pix directory of your theme.

* /theme/yourthemename/pix/imageone.jpg
* /theme/yourthemename/pix/subdir/imagetwo.png

Notice that one image is a JPEG image, and the second is a PNG. Also the second image is in a subdirectory.

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>
In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {background-image:url([[pix:theme|imageone]]);}
.divtwo {background-image:url([[pix:theme|subdir/imagetwo]]);}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

The final thing to notice with both of the cases above is that at no point do we include the images file extension.
The reason for this leads us into the next topic, how to override images.

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix/moodlelogo.gif
# /theme/themename/pix/i/user.gif
How easy is that!

Now the other very cool thing to mention is that Moodle looks for not just replacements of the same image type (jpg, gif, etc...) but also replacements in any image format. This is why above when working with our images we never specified the images file extension.
This means that the following would also work:
# /theme/themename/pix/moodlelogo.png
# /theme/themename/pix/i/user.bmp

For a more detailed description of how this all works see the page on [[Development:Themes_2.0_How_to_use_images_within_your_theme|using images within your theme]]

==Unobvious Things==
===Getting Your Theme to Appear Correctly in Theme Selector===
If you follow the examples on this page to the letter, when you go to the Theme Selector page you may be discouraged to find that your theme does not appear like the other themes do. In fact, instead of your theme's name, you will see something along the lines of <nowiki>[[pluginname]]</nowiki>.

To correct this, you must add the /lang/en/theme_THEMENAME.php file, where THEMENAME is the name of the theme folder. Inside that file, add the string "$string['pluginname'] = 'THEMENAME'; ". Make THEMENAME the name of your theme, however you want it displayed in the Theme selector.

The screenshot for the theme should be about 500x400 px.

===Required theme divs===

Some parts of Moodle may rely on particular divs, for example the div with id 'page-header'.

Consequently all themes must include at least the divs (with the same ids) that are present in the 'base' theme.

Missing out these elements may result in unexpected behaviour within specific modules or other plugins.

==Appendix A==
===Theme options as of April 28th, 2010===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|}
===The different layouts as of August 17th, 2010===
{| class="nicetable" id="theme_layouts_table"
|-
! Layout
! Purpose
|-
| base
| Most backwards compatible layout without the blocks - this is the layout used by default.
|-
| standard
| Standard layout with blocks, this is recommended for most pages with general information.
|-
| course
| Main course page.
|-
| coursecategory
| Use for browsing through course categories.
|-
| incourse
| Default layout while browsing a course, typical for modules.
|-
| frontpage
| The site home page.
|-
| admin
| Administration pages and scripts.
|-
| mydashboard
| My dashboard page.
|-
| mypublic
| My public page.
|-
| login
| The login page.
|-
| popup
| Pages that appear in pop-up windows - no navigation, no blocks, no header.
|-
| frametop
| Used for legacy frame layouts only. No blocks and minimal footer.
|-
| embedded
| Embeded pages, like iframe/object embedded in moodleform - it needs as much space as possible
|-
| maintenance
| Used during upgrade and install. This must not have any blocks, and it is good idea if it does not have links to other places - for example there should not be a home link in the footer.
|-
| print
| Used when the page is being displayed specifically for printing.
|}

==See also==

* [http://www.youtube.com/watch?v=OvaU54uh-qA New themes in Moodle 2.0 video]
* [[Development:Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Development:Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Development:Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Development:Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Development:Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Development:Styling and customising the dock]] - How to style and customise the dock.
* [[Development:Theme changes in 2.0]]
* [[Development:Using jQuery with Moodle 2.0]]

[[de:Designs 2.0]]
[[es:Temas 2.0]]

Development:Backup 2.0 theme data

2011-03-08T12:09:10Z

Quen:

{{Template:Development:Backup 2.0}}{{Moodle_2.0}}

== Introduction ==

In Moodle 2, themes can have data tables and files which can be backed up with a course. (To create data tables in a theme, use the standard <tt>db</tt> folder.)

None of the standard themes have any course-related data so it is not obvious how to code the backup and restore for them. This page gives an example theme as a case study which you can use to implement your own backup code for a theme which contains per-course data.

'''Note: Theme data backup requires Moodle 2.0.3 or later.'''

== Example: the 'ou' theme ==

Our theme called the 'ou' theme (i.e. in the folder theme/ou) contains the following per-course data which needs to be backed up:

* Each course using the theme can select a different colour (referred to as 'variant' of the theme). This is so we can have different courses in any of 10 different colours without having to make 10 different themes.

* Each course can also select a custom image which is used in the header on some screens. This is so we can have cute kitten pictures on our test servers.

The variant is stored in a table called <tt>theme_ou_courseoptions</tt>. This table has 3 fields: <tt>id</tt>, <tt>courseid</tt>, and <tt>variant</tt>. (If we ever need to add more theme data, we can add fields to it.)

The image file is stored using the Moodle file API at the course context, in the <tt>theme_ou</tt> component and the <tt>image</tt> file area.

=== Backup ===

The backup code is in the file <tt>theme/ou/backup/moodle2/backup_theme_ou_plugin.class.php</tt>. Leaving out the headers, this file looks like:

class backup_theme_ou_plugin extends backup_theme_plugin {

/**
* Returns the theme information to attach to course element
*/
protected function define_course_plugin_structure() {
// Define virtual plugin element
$plugin = $this->get_plugin_element(null, $this->get_theme_condition(), 'ou');

// Create plugin container element with standard name
$pluginwrapper = new backup_nested_element($this->get_recommended_name());

// Add wrapper to plugin
$plugin->add_child($pluginwrapper);

// Set up theme's own structure and add to wrapper
$studyplan = new backup_nested_element('ou', array('id'), array(
'variant'));
$pluginwrapper->add_child($studyplan);

// Use database to get source
$studyplan->set_source_table('theme_ou_courseoptions',
array('courseid' => backup::VAR_COURSEID));

// Include files which have theme_ou and area image and no itemid
$studyplan->annotate_files('theme_ou', 'image', null);

return $plugin;
}
}

As you can see this works in a similar way to backup for modules and other plugins. The first line:

$this->get_plugin_element(null, $this->get_theme_condition(), 'ou');

means that the theme data will only be backed up if the current theme for the course is actually the 'ou' theme. In other words, if you change the course theme to 'standard', this backup data will not be created. (It is possible to change this behaviour if you want to backup theme data even when a different theme is currently selected for the course; leave out the last two parameters.)

You can see how you would change the code to use a different theme name, database table, fields, or file area. It's also possible to add a more complicated data structured in the same way as for other plugins. You could even store user data - however, unless the user data is course-specific, it would probably be more appropriate to store user theme options in user preferences rather than within theme-managed tables.

==== Testing ====

To test the backup, carry it out and then look inside the resulting zip file. In the <tt>course</tt> folder there should be a file called <tt>course.xml</tt>. If theme data is backed up, it will include a section like the following:

<plugin_theme_ou_course>
<ou id="2">
<variant>purple</variant>
</ou>
</plugin_theme_ou_course>

Additionally, if the file backup worked, you should be able to find any files from within the specified file area inside the 'files' section of the backup (it will help if you know the hash code of the file; otherwise, note the size and make sure the test course doesn't have many other files to look through).

If you switch the course to a different theme, this data will not be backed up.

=== Restore ===

Unsurprisingly, restore code goes in the file <tt>theme/ou/backup/moodle2/restore_theme_ou_plugin.class.php</tt>. Leaving out the headers, this file is:

class restore_theme_ou_plugin extends restore_theme_plugin {

/**
* Returns the paths to be handled by the plugin at course level
*/
protected function define_course_plugin_structure() {
$paths = array();

// Because of using get_recommended_name() it is able to find the
// correct path just by using the part inside the element name (which
// only has a /ou element).
$elepath = $this->get_pathfor('/ou');

// The 'ou' here defines that it will use the process_ou function
// to restore its element.
$paths[] = new restore_path_element('ou', $elepath);

return $paths;
}

/**
* Called after this runs for a course.
*/
function after_execute_course() {
// Need to restore file
$this->add_related_files('theme_ou', 'image', null);
}

/**
* Process the 'ou' element
*/
public function process_ou($data) {
global $DB;

// Get data record ready to insert in database
$data = (object)$data;
$data->courseid = $this->task->get_courseid();

// See if there is an existing record for this course
$existingid = $DB->get_field('theme_ou_courseoptions', 'id',
array('courseid'=>$data->courseid));
if ($existingid) {
$data->id = $existingid;
$DB->update_record('theme_ou_courseoptions', data);
} else {
$DB->insert_record('theme_ou_courseoptions', $data);
}

// No need to record the old/new id as nothing ever refers to
// the id of this table.
}
}

Again this is just the same as restoring a module. To change this to support your own theme, you would change the word 'ou' to your own theme's name, change references to the <tt>theme_ou_courseoptions</tt> table to your own data table (or otherwise change what exactly it does when restoring), and change the file area details in the <tt>add_related_files</tt> call.

Unlike backup, the restore code always runs if the data was included in the backup, even if the course actually has a different theme once it is restored (e.g. the site default theme has changed). This should not cause a particular problem; at worst you'll get a superfluous database row on rare occasions.

==== Testing ====

It is probably obvious how to test restore :) Once you've verified that backup is producing the correct XML data, just check that restore recreates the necessary data for you.

In our case, we know restore works if the restored course is purple and has a cute kitten picture.

Development:Backup 2.0 theme data

2011-03-08T12:03:52Z

Quen: New page: {{Template:Development:Backup 2.0}}{{Moodle_2.0}} == Introduction == In Moodle 2, themes can have data tables and files which can be backed up with a course. (To create data tables in a ...

Development:Backup 2.0 for developers

2011-03-08T11:46:03Z

Quen:

{{Template:Development:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}

== Introduction ==

This page tries to explain, from a development perspective, '''how to implement''' the backup feature for various Moodle 2.x plugins, mainly, modules and blocks.

Note that, at the time of writing this, the backup & restore subsystem itself is '''under development''', so still there are some missing bits, specially about the way to handle '''subplugins''' (question types, data fields...) under the new backup infrastructure, so any module using such artifacts, like data, assignment, quiz, workshop, aren't good candidates right now. This will be addressed (and this Docs updated) once we have determined how each subplugin is expected to work (from a DB / backup perspective).

Everything in backup '''is about tasks and steps''' (see [[Development:Backup 2.0 general architecture|Backup 2.0 general architecture]] for more information), all them conforming one backup plan. Each module instance and each block instance will be backup by one backup task instance that is, basically, one collection of backup steps. How steps are organized within the task will dictate to the backup system what to do and in which order.

Another important point is that Moodle backup 2.0, supports '''multiple backup formats''' ("moodle2", "imscc"...) each one having its own tasks/steps, completely unrelated between them. In any case, for now, we are focusing all the explanations below in the "moodle2" format, that is the one required in order to keep any module/block '''transportable between Moodle instances''' without any loss of data. Surely, for the rest of formats, we'll end with other documents describing them, as far as each one can have its own particularities.

Talking about backup steps we must differentiate '''two type of steps''':

* '''Execution steps''': That, simply, execute arbitrary PHP code. They are useful to prepare different structures, create directories, whatever have to be done not involving the generation of XML files. Normally you won't need them.
* '''Structure steps''': That, using one PHP API (detailed below) define completely the XML structure to be exported and its contents. Hopefully, "normal" modules only will have to use one step of this type in order to have the backup functionality 100% implemented.

Said that, in the next steps we are going through all the steps necessary to create the backup of one simple module and one block, in order to get all the possibilities covered.

== How to backup one module ==

For this section, we have selected one simple module (choice) that requires practically all the backup "machinery" to be used, so it will get explained as we progress in the development. The only point not covered here are the "subplugin" facilities, covered later in a separate section.

=== Prerequisites ===

In order to achieve the backup implementation for the module, some prerequisites should be fulfilled. They are just recommendations but, specially while getting used to backup, it's good to follow them. Let's see:

# '''Learn about the module'''. If you aren't the creator of the module, spend some time playing with the module, creating and using it, exploring each one of its functionalities. By doing this you will end with some "real" data in the module instances that will be really useful when testing / debugging how the module backup is being generated.
# '''Draw one schema of the module''' DB structures. While you are playing with the module, look continuously to the DB, how records are saved and which are the relations between the module's tables. As far a backup is, basically, one "selective dump" of those tables, knowing the maximum about them is highly recommended. At the end, you must end with one tree structure will be the basis for the generated XML file.
# '''Annotate which tables contain user-related info''' and which ones don't. One of the core functionalities that must be present on each module is the ability to include user related information or skipping it, so you will need that information later.

'''Tip''': If the module already existed before Moodle 2.0, it can be a '''good idea''' to take a look to its 1.9 backuplib.php file, as far as the structure is already defined there and can help to understand the organization better and, at the same time, '''keeping the XML structure as similar as possible''', that will, definitively, '''make things easier''' when converting 1.9 backup files to the new backup 2.0 format.

'''Note''': It's important to highlight that the structure schema, once decided, should be as stable as possible along the time, because any change in the structure makes restore really way-more-more complex to be implemented. There isn't problems adding / deleting fields, nor adding new elements to the structure. But '''the structure (tree) itself must persist as stable as possible''', so please, be careful when deciding it.

So, applying these pre-requisites to our candidate module (choice), here it's the corresponding schema. We'll use it along the whole process.

=== Schema ===

In the schema, you must try to put as much information as possible, so that will produce the coding process later to be quicker and easier while keeping the final results free from errors and missing bits. So, once more, don't start coding immediately, instead spend some time with the requisites above, understanding how the module works and designing the final structure that represents it better.

==== The (correct) candidate ====

[[Image:Backup20 choice alt.png‎|left|Alternative choice backup structure]]

The tree on the left shows the ER/DB structure of the choice module, where one choice have one or more options and each option is answered by users one or more times (note: ignore cardinality accuracy in the previous phrase).

And that's the best schema representing the structure of the module, with each element properly nested so, we won't have any problem with restore as far as the order required by restore (1, 2, 3) are naturally given.

Looks easy, cool, but follow reading… you will get surprised! :-)<br style="clear: both" />

==== The (chosen) candidate ====

Instead we are going to use the (complete this time) diagram below. See the rationale about that after the image.

[[Image:Backup20 choice.png‎|center|Used choice backup structure]]

The main reason to use this tree (instead of the "correct") one is that this is the structure that has been used by Moodle 1.9 backup since ages ago for the choice module and, of course have done its work ok. As commented above we must '''try to reduce the number of structural changes''' in one module backup in order to keep the restore operations working along the time (the same is applicable for the conversion of 1.9 backup files to the new 2.0 format). Finally, this is a good example about how one module '''can have different XML representations''' and we need to try to get that best one (this is not the case) on each case. So, once more, '''spending some time analyzing''' the activity is worth it.

Let's analyze the schema with some detail:

* '''Detecting user information''': We must be able to define the entities (tables) in the diagram that are used to store user information. One of the core features of the backup subsystem since its early days have been the ability to produce backup with and without user information. So we need that info. Hence, the "no user info" in the choice and choice_options elements (they are configuration, user-independent), while the choice_answers is marked as "user info" (contains user's answers to the choice).

* '''Determining the correct order of backup''': This, while simple, is critical too (especially from a restore perspective). As far as the restore reads progressively the xml file and performs actions in that order, we '''must guarantee that the "read order" is the correct''' one, fulfilling any possible dependency. Back to our schema it's clear that we need to backup the "choice" element at first, and then the "choice_options" and "choice_answers" ones. More yet, the "choice_options" must be backup before "choice_answers" as far as the later needs to save the values of the former (the "optionid" information). Be noted, that, as commented some paragraphs above, the "correct" alternative really gave us that order information easily. Doesn't matter as far as we have been able to establish it also in the "chosen" schema.

* '''Attributes and elements''': Now it's time to decide which fields will be considered attributes in the resulting XML file and which ones will be child elements (tags). The rule is simple: '''All the "id" fields must (should) be defined as attributes'''. Note this is just one arbitrary rule without much rationale behind it as far as, from a restore perspective, everything (attributes and child tags) will be handled in the same way (object attributes). So, in our schema, all the "id" fields have been marked as "attr".

* '''Not needed elements''': If we have designed properly the schema, we'll detect that some fields aren't necessary, as far as such information is already included in some parent element. In our schema, the field "choiceid", pointing to the "choice->id", both in the options and in the answer elements have been marked as "not needed" as far as their parent "choice" already contains it. Something similar happens with the "course" field in the choice element, it doesn't need to be included in the backup file as far as something above it (course element, out from the module scope) already has it defined. Finally, there is one element marked as "needed" that shows us, once more, that the schema we are using is not the best. In the "chosen" one, as far as "choice_answers" isn't nested under "choice_options" we must keep that field in the backup, or restore won't know to which option each answer belongs to. Instead, with the "correct" schema, where answers are nested under options, that field is not needed. Summarizing, '''any field, but those already existing in parent elements must be included in backup'''.

* '''Detecting file areas used by the module''': Along the module we can be using various file areas in different elements and fields. We need to know exactly which file area is handled by which element and the (optional) itemid information used for that file area. In general, '''anything being one text field, or anything looking like one attachment''' has high chances to have one (hidden) file area associated. In our schema, we have one file area detected (choice_intro) corresponding to the introduction of the module and available to put any images or whatever in that field. Also, in general, all the "xxx_intro" file areas use to have no itemid, as far as the module's context is enough to define them without ambiguities. So, we mark the choice->intro as "choice_intro" file area and "no itemid"). From our expertise playing with the module we know there aren't more file areas at all.

* <span id="annotate_is_important">'''Annotating some important bits''':</span> Due to the modularity of the backup and in order to know exactly which information must be saved (because it's used) and which one can be skipped, '''it's important to annotate some important elements along the whole backup''' process. So, back to our schema, we have marked the "choice_answer->userid" field as "annotation" (so backup will, automatically, add all the information for that user). Here it's the list of elements that we must not forget to annotate (or we could end with non-restorable backups). Note that we must, always, be annotating "id" values and not other types of data:
** '''user''': Any field pointing to one user->id present along the schema (as said above, our schema has one).
** '''grouping''': Any field pointing to one grouping->id
** '''group''': Any field pointing to one group->id
** '''role''': Any field pointing to one role->id
** '''scale''': Any field pointing to one scale->id
** '''outcome''': Any field pointing to one outcome->id

And this is all the information we need to know, before starting to code. Surely, once used to backup and restore, you will be able to start coding sooner, but '''don't forget about the importance of choosing one good and stable structure''' before anything else. It's really the critical part of any module's backup.

Said that, let's see how to code all this information in order to get one cool backup for our beloved module.

=== Coding ===

Already here? Have you read, al least once, all the explanations and comments in the previous sections? Yes? Sure? I can imagine it's hard to read so much text, just imagine how hard is to write it! Go, go, go and read it!

Jokes apart, in this section we are going to code the module's (choice) backup code. As you'll see soon, all the information gathered in previous steps is really important and will make the coding task easier and less prone to errors.

==== Setting up the environment ====

By default, any backup operation will end with one .zip file stored in some course / section / activity area. That means that, each time you execute one backup, you'll need to go across the web interface to that file area, download the generated .zip file, uncompress it and then, see how things have been generated. And you will be executing a bunch of backup files until you get everything working as expected, so the whole develop / test process isn't really "agile". To improve things a bit, there is one $CFG setting that you should consider using '''in your development environment'''. Just put this in your config.php:

<code php>
$CFG->keeptempdirectoriesonbackup = true;
</code>

With this setting enabled, backup won't delete the temporary directory where everything is calculated, so you will be able to access to it directly, skipping all the ui / download / unzip steps above. Those temp directories are under $CFG->dataroot/temp/backup. Note that, for each backup invocation, a new directory is created.

Also, in order to be able to execute backups quickly (instead of navigating along the UI), you can, simply, put one script like this in your $CFG->dirroot directory:

<code php>
<?php

require_once('config.php');
require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');

$course_module_to_backup = XX; // Set this to one existing choice cmid in your dev site
$user_doing_the_backup = YY; // Set this to the id of your admin accouun

$bc = new backup_controller(backup::TYPE_1ACTIVITY, $course_module_to_backup, backup::FORMAT_MOODLE,
backup::INTERACTIVE_NO, backup::MODE_GENERAL, $user_doing_the_backup);
$bc->execute_plan();
</code>

just set proper values for XX and YY above and execute it from your browser. If you get one error about one not found class (with the name of your module) everything is ok.

==== Required stuff ====

The first thing you need to make is to, explicitly, declare that your module (choice in our example) is going to support the MOODLE2 backup format, to do so, you need to go to mod/choice/lib.php and, in the choice_supports() function add one new feature by adding this line:

<code php>
case FEATURE_BACKUP_MOODLE2: return true;
</code>

If you execute another backup (with the script provided above, you will continue getting one error, as far as we haven't still coded anything related to backup, that's ok.

Next step is to create the directory where all the backup code for the choice module will be. Just create the directory(s) mod/choice/backup/moodle2

At this point, we have all the required stuff ready and all the pending tasks will be done under that recently created directory.

==== Settings, Steps and Tasks ====

In the introduction of the tutorial, we commented about backup being structured into tasks, each one being one collection of steps (and potentially using some custom settings). Those are, exactly, the objects that we need to create to achieve the backup functionality in our module.

First of all, lets' create the settings file, where all the custom settings to be used by our module will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_settingslib.php''' and their contents are really meaningful:

<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 moodlecore
* @subpackage backup-moodle2
* @copyright 2010 onwards YOUR_NAME_GOES_HERE {@link YOUR_URL_GOES_HERE}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// This activity has not particular settings but the inherited from the generic
// backup_activity_task so here there isn't any class definition, like the ones
// existing in /backup/moodle2/backup_settingslib.php (activities section)
</code>

Looks simple, isn't it? Nothing but a few comments. This is looking really easy. For now, we aren't going to introduce any custom setting for any module, only the "core activity settings" will be used. Once backup and Moodle 2.0 is stable we can start analyzing useful settings to customize how the module's backup is performed. For now, just leave it blank, please. In fact, if it's empty,''' you can safely not create it''' at all. It's here just for explanation purposes.

Side note: To save some space, we only will be showing the © message/license in the code above. Just add it to each file created.

Now we are going to create the steps file, where all the steps to be executed by our backup activity task will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' and their contents are these:

<code php>
<?php

/**
* Define all the backup steps that will be used by the backup_choice_activity_task
*/
</code>

Yes, it's another empty file. No worries we'll fill it later.

Finally we need to create the task file, where our just created settings and steps files will be included and used. It must be named '''mod/choice/backup/moodle2/backup_choice_activity_task.class.php''' and their contents are these:

<code php>
<?php

require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_stepslib.php'); // Because it exists (must)
require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_settingslib.php'); // Because it exists (optional)

/**
* choice backup task that provides all the settings and steps to perform one
* complete backup of the activity
*/
class backup_choice_activity_task extends backup_activity_task {

/**
* Define (add) particular settings this activity can have
*/
protected function define_my_settings() {
// No particular settings for this activity
}

/**
* Define (add) particular steps this activity can have
*/
protected function define_my_steps() {
// Choice only has one structure step
}

/**
* Code the transformations to perform in the activity in
* order to get transportable (encoded) links
*/
static public function encode_content_links($content) {
return $content;
}
}
</code>

This is the main file (class) of the choice backup and it will be used to define any setting (define_my_settings() method) and any step (define_my_steps() method) to be executed in the backup process. It also contains one 3rd method (encode_content_links($content)) that will allow manually URLs pointing to the choice to be properly converted when the choice is moved to other site / course using the backup / restore functionality.

As you see, for now, the three required methods are doing nothing. Just execute the backup again. Wow, no errors anymore. We have already fulfilled all the minimum coding needs in order to have the choice backup working.

Now you should go to your $CFG->dataroot/temp/backup/xxxx directory (the more recent) and spend some time looking what has been created under the activities/choice_XX directory. There is already a lot of stuff that backup has generated for you: comments, blocks, logs, grades, module info, roles... some of them empty and others already showing real information.

In any case, now, we need to add one important file there, the "choice.xml" where the real information for your module will be present, following the specs given by the schema we decided some sections above.

So, let's go, it's time to create our choice structure step. To do so, we edit the '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' file and add this code after the existing comments:

<code php>
/**
* Define the complete choice structure for backup, with file and id annotations
*/
class backup_choice_activity_structure_step extends backup_activity_structure_step {

protected function define_structure() {

// To know if we are including userinfo
$userinfo = $this->get_setting_value('userinfo');

// Define each element separated

// Build the tree

// Define sources

// Define id annotations

// Define file annotations

// Return the root element (choice), wrapped into standard activity structure

}
}
</code>

So, we have defined one structure step that will be the responsible, using one PHP API to provide backup with all the information needed to generate the choice.xml file. Now, go back to the task file and add these contents in the define_my_steps() methods:

<code php>
$this->add_step(new backup_choice_activity_structure_step('choice_structure', 'choice.xml'));
</code>

That way, our choice task knows it must execute one new step, the one involving the generation of the choice.xml file. Let's execute one new backup and see results.You should be getting one new error with something like that "backup_structure_step_wrong_structure". It means that everything is ok up to now, the task has tried to execute the structure step, but this is not properly defined.

===== Defining each element =====

So, next step is about to define the choice structure. Going back to our step, under the ''// Define each element separate'' comment we'll add this code:

<code php>
$choice = new backup_nested_element('choice', array('id'), array(
'name', 'intro', 'introformat', 'publish',
'showresults', 'display', 'allowupdate', 'allowunanswered',
'limitanswers', 'timeopen', 'timeclose', 'timemodified'));

$options = new backup_nested_element('options');

$option = new backup_nested_element('option', array('id'), array(
'text', 'maxanswers', 'timemodified'));

$answers = new backup_nested_element('answers');

$answer = new backup_nested_element('answer', array('id'), array(
'userid', 'optionid', 'timemodified'));
</code>

===== Return the root element =====

And also, in order to get it working, let's define the return element, so, after the ''// Return the root element'' comment, add this code:

<code php>
return $this->prepare_activity_structure($choice);
</code>

Now we can execute the backup again and, a long as we have already defined the root element of the module, should have now one choice.xml file created (without proper contents but must be there).

About the code above, all we have done is to define, separately each element that will be part of the choice.xml file. Special note about the $options and $answers elements. Since Moodle 1.9 we use to enclose real elements (the singular ones) inside one extra plural element, hence we create them here (as empty elements without attributes nor child tags). About the rest (the singular ones) we use 3 params in the instantiation:
* The name of the element
* One array of attributes of the element
* One array of child tags (fields) of the element.
And we include all the fields that previously we had defined in our schema '''but''' the ones marked as '''not needed'''.

===== Building the tree =====

Now it's time to declare the relations between all those elements, so, after the ''// Build the tree'' comment we'll add this code:

<code php>
$choice->add_child($options);
$options->add_child($option);

$choice->add_child($answers);
$answers->add_child($answer);
</code>

Self explanatory, using $choice as root element, we define the whole tree using the add_child() method. And, of course, we respect '''the order''' that we had decided, so $options will be '''physically''' before $answers in the tree (and in the generated XML).

===== Defining the sources =====

After this, it's the moment to instruct our tree about how to fetch information from DB in order to generate the choice.xml file, so after the ''// Define sources'' comment, we'll add this code:

<code php>
$choice->set_source_table('choice', array('id' => backup::VAR_ACTIVITYID));

$option->set_source_sql('
SELECT *
FROM {choice_options}
WHERE choiceid = ?',
array(backup::VAR_PARENTID));

// All the rest of elements only happen if we are including user info
if ($userinfo) {
$answer->set_source_table('choice_answers', array('choiceid' => '../../id'));
}
</code>

So we define the source for the $choice element as the information present in the 'choice' table for the id that is being backup (backup::VAR_ACTIVITYID). Or we define the source for the $option element like one SQL (could have been one table too, just to show more possibilities of the API, using the parent (the choice one) as value for the query (backup::VAR_PARENTID).

And finally, conditionally, if user information is going to be included, we define the source for the $answer (note we had already annotated in our schema that this element was dependent of that).

And we define the source condition as having the 'choiceid' field matching the value of the 'id' field two levels above (../../id). If you follow the tree created in the previous code section, that's exactly the choice->id (remember we have introduced one extra level (the plural one between the 'choice' and the 'answer' singular elements). Note this is 100% equivalent to use backup::VAR_PARENTID (as we have done in the $option source) just used to show possibilities of the API.

Summarizing, with the API, we have these 3 method for defining sources:

* '''set_source_table($tablename, array $conditions)''': When the information is get straight from one table (vast majority of cases in backup)
* '''set_source_sql($sql, array $params)''': When the information doesn't map one table directly and we need something more complex
* '''set_source_array($array)''': When we have some fixed information to backup. Not really useful in nested information, but used by core here and there.

Note that both the $conditions and $params above only accept one limited number of constants or values (not all available in all backups!), mainly:

* '''backup::VAR_COURSEID''': The id of the course this activity belongs to / the course id being backup
* '''backup::VAR_SECTIONID''': The id of the section this activity belongs to / the section id being backup
* '''backup::VAR_ACTIVITYID''': The id of the activity id being backup
* '''backup::VAR_MODID''': The id of the course_module being backup
* '''backup::VAR_MODULENAME''': The name of the module being backup
* '''backup::VAR_BLOCKID''': The id of the block being backup
* '''backup::VAR_BLOCKNAME''': The name of the block being backup
* '''backup::VAR_CONTEXTID''': The context id of the activity / course being backup
* '''backup::VAR_PARENTID''': The value of the first parent id found in the structure.
* '''../some/path/to/parent''': To manually point to other value of any parent.

Is important to note that, in 99% of the case we should be using, exclusively, some of the constants above, and backup, automatically will handle them properly. In case we have any other condition or param to be added like, for example, the number 23, or the string 'user', we cannot add them directly, but enclose them with the helper '''backup_helper::is_sqlparam(23)''' or '''backup_helper::is_sqlparam('user')'''. That way backup will know they are raw SQL params not needing any special handling, like the constants above.

Well, now it's time to run backup again and take a look to our activities/choice_XX/choice.xml file. Now everything should be there, properly nested, the choice, the options and the answers. We are really near finishing now.

===== Annotating IDs =====

Now it's time to perform all the annotations that we had already detected in our analysis of the module. So, after the ''// Define id annotations'' comment we'll be adding:

<code php>
$answer->annotate_ids('user', 'userid');
</code>

It simply means, annotate for each $answer element, the value of the 'userid' field as one 'user' to be backup. In other words we are instructing backup that there is one new user to include later, when generating the users information and, at the same time, we are determining that those users are needed for the choice XX, so, if on restore we decide to skip that choice and such user isn't necessary for any other module / subsystem, it won't be restored. All this "uses" information is handled by the "inforef.xml" files within each activity backup, just in case you're interested to take a look to them. Else, just consider them, "dark magic".

'''Note''': If you're not sure about which elements must be annotated, review [[Development:Backup 2.0 for developers #annotate_is_important|"Annotating some important bits"]] above for details about '''must-be-done''' annotations.

===== Annotating files =====

And, finally, reviewing our ellaborated and detailed schema, the last thing we need to take rid of are the file areas used, so, after the ''// Define file annotations'' comment we'll add:

<code php>
$choice->annotate_files('mod_choice', 'intro', null); // This file area hasn't itemid
</code>

That means that, within the $choice element we have one file area in use, of course belonging to the 'mod_choice' component (where all the choice module files belong to), named 'intro' and not using itemid (null). Note that, as far as it is possible to have multiple file areas in the same element (table), you may end having multiple calls to that method, one for each filearea to be added to backup. About the third parameter, in case we need it, it must be the name of one of the attributes or fields of the $choice element (usually, in the vast majority of cases, the 'id' of the element), otherwise we'll use null.

=== One encoded wor(l)d ===

Already out from the step definition, that should be working ok now, with the choice.xml file being generated and all the annotations being processed and added to the inforef.xml file, there is one more point to fulfill before considering choice's backup 100% finished.

And it's about how to provide the ability to transform some links to the choice module when the backup file is restored into another server / course. That is automatically handled by a two-step approach:
# On backup, we transform as many well-know URLs as possible to one encoded form.
# On restore, we transform those encoded URLS back to their original form, but pointing to their new targets.

So, in backup, we must provide services for the point 1 above, and that is done by adding some "encoding" conversions to the '''encode_content_links()''' method in our '''backup_choice_activity_task'''. So, define it to look like this

<code php>
/**
* Code the transformations to perform in the activity in
* order to get transportable (encoded) links
*/
static public function encode_content_links($content) {
global $CFG;

$base = preg_quote($CFG->wwwroot,"/");

// Link to the list of choices
$search="/(".$base."\/mod\/choice\/index.php\?id\=)([0-9]+)/";
$content= preg_replace($search, '$@CHOICEINDEX*$2@$', $content);

// Link to choice view by moduleid
$search="/(".$base."\/mod\/choice\/view.php\?id\=)([0-9]+)/";
$content= preg_replace($search, '$@CHOICEVIEWBYID*$2@$', $content);

return $content;
}
</code>

Básically, it gets any URL (manually written) in any content of the backup being generated and transform some (well-known) URLs to one encoded alternative. In this case we are encoding:
* Any URL pointing to the list of choices in a course == is changed to ==> $@CHOICEINDEX*XX@$
* Any URL pointing to one exact choice == is changed to ==> $@CHOICEVIEWBYID*YY@$

In restore, well have the opposite conversions happening, replacing the XX and YY above to their new equivalents, so those links will be transportable via backup/restore without any need to edit them manually later.

Tip: Don't forget to look to the module's 1.9 backup code, as far as there you'll find which conversions must be considered to be added here.

=== Final notes ===

* Don't get stressed, it's really more difficult / longer to explain than to do it. 100% guaranteed, else we'll return your money. :-P
* If you've become lost, or your code is not working properly, you always can [http://cvs.moodle.org/moodle/mod/choice/backup/moodle2/ see the complete choice working code in CVS]. Or, alternatively, look to other well known modules, like [http://cvs.moodle.org/moodle/mod/forum/backup/moodle2/ forum] or also the [http://cvs.moodle.org/moodle/backup/moodle2/backup_stepslib.php?view=markup big core library of steps], where you will find all sort of uses of the API.
* If you are going to implement backup for module XXXX, just copy this document, replace any "choice" occurrence within it by XXXX and follow it from the beginning to the end. Should work.
* If the module already existed in Moodle 1.x, try to follow the same structure if possible, that will make things easier for restore / conversion.
* Right now there are some pending tasks related with different exceptions that will be thrown if you code something wrongly (bad nesting, incorrect field names, bad constant/sql param uses...) and how they are shown. Fix for that will be coming soon.
* Also, as stated at the beginning of this tutorial, we are still missing "subplugins" final support in modules, so try to avoid implementing backup on them for now. Once ready, there will be one new section in this document about them.
* Any question / improvement / comment, feel free to contact with Moodle HQ, better if using the Tracker or, alternatively, forums / email / direct contact with your very-best-developer-friend. Note this is version x.0 (dot zero) of the backup API, so sure there are possibilities to improve it along the time.

== Other components that can be backed up ==

Most plugins which can be added to a course can also include data in a course backup. Some examples:

* Course formats
* Themes: [[Development: Backup 2.0 theme data| Backup 2.0 theme data]]

Development:Module visibility and display

2011-02-16T18:17:24Z

Quen: /* get_fast_modinfo data */

{{Moodle 2.0}}

The features described here are available since Moodle 2.0.2.

== Summary ==

A new API allows you to customise how your module displays on the main course page:

* You can display custom HTML below the link to your module.

* If your module does not have a link (like Label, where it is only for display on the main page) then you can remove the link from the main page and from all navigation etc.

* You can display HTML next to the link to your module that indicates dynamic information (like Forum, where it displays information about unread messages).

* You can display additional icons next to the other module editing icons when the user is editing the page.

In addition, existing things you could already do (like change the icon on the main page) are still available when using the new API.

The <tt>get_fast_modinfo</tt> function now returns specific classes which are documented and which you can use to obtain new information about modules.

== Backward compatibility ==

All modules and code written for Moodle 2.0 should continue to behave in exactly the same manner. There is no need to change existing modules for this API unless you want to use the new features.

== Removing your link ==

If your module should not appear in navigation and in other lists of modules to visit or get information for, like Label, the easiest way to remove that link is to return true for FEATURE_NO_VIEW_LINK in your module's <tt>_supports</tt> function.

== Customising module display, in cache ==

The first place you can customise your module display is in the existing <tt>_get_coursemodule_info</tt> API function. This function obtains information about the module which will be stored in the course cache (the <tt>modinfo</tt> field of the course table).

The course cache is only updated when somebody edits a module, so it can't be used for dynamic information - but it's okay if it takes a few database queries to calculate the data because it will be cached for future use.

The function should return a value of class <tt>cached_cm_info</tt>. For example:

<code php>
function mod_frog_get_coursemodule_info($cm) {
$info = new cached_cm_info;
$info->content = '<p>This will display below the module.</p>';
return $info;
}
</code>

You can change several properties which are documented in that class definition. If you don't change a property, its value remains default.

* <tt>name</tt> - name of activity (text of the link on course page).
* <tt>icon</tt>, <tt>iconcomponent</tt> - name and component name of icon to display by the link.
* <tt>content</tt> - extra HTML content to display below the module link on course page (not shown in navigation etc).
* <tt>customdata</tt> - arbitrary extra PHP data to store in modinfo cache; useful if, for performance reasons, your module needs to store data that should be accessible very quickly from other parts of the course.
* <tt>extraclasses</tt> - extra CSS class or classes that will be added to the activity on the main page, so that you can alter the styling.
* <tt>onclick</tt> - already-escaped HTML that will be inserted as the value of the onclick attribute.

If you don't need the information to be cached (it can be retrieved very quickly without making any database queries) then you might consider using one of the functions below instead, in order to avoid unnecessarily increasing the size of the course cache. Although the headings mention the current user, you can of course use those functions in a way that doesn't depend on the current user.

== Customising module display, for current user ==

You can customise module display dynamically (when the page loads). For example you might want to alter it based on the permissions of the current user.

<code php>
function mod_frog_cm_info_dynamic(cm_info $cm) {
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
if (!has_capability('some/capability', $context)) {
$cm->set_user_visible(false);
}
}
</code>

This code can affect the navigation, and whether users are permitted to access the module (as above). It runs on all pages within the course, so it's very important that you do not put slow code in this function: it should not make any database queries.

In addition to the <tt>set_user_visible</tt> function shown, you can also set many other things such as additional editing icons which will appear if editing mode is enabled. See the cm_info class documentation for more information.

Most things are set using functions (as above; another example would be <tt>set_content</tt> which sets the same content data as mentioned in the previous section) while other things can be set directly using public variables.

== Customising module display, for current user, on course page only ==

Sometimes you need to display custom information for the current user that appears only on the course view page. For example, the forum module displays unread information on the view page. This information doesn't show on other pages (it isn't included in the navigation, for instance).

<code php>
function mod_frog_cm_info_view(cm_info $cm) {
$cm->set_after_link('Last tadpole: 22:17');
}
</code>

Because this function only runs when looking at the course page:

* It is OK to do tasks which may require some database queries (such as checking for unread forum messages), although obviously this should be kept to a minimum. In particular, care should be taken so that if there are 20 instances of the activity on the course page, it doesn't make 20 separate queries to obtain the information.

* Inside this function you cannot set options which affect the appearance or access to the activity on other pages; for example, you cannot turn off the uservisible flag as shown in the previous example. This is because these options are required on other pages (e.g. to display navigation) so it does not make sense to set them only for the course page. If you try, you'll get a <tt>coding_exception</tt>.

== get_fast_modinfo data ==

The function <tt>get_fast_modinfo</tt> now returns an object of class course_modinfo, which itself contains cm_info objects about each activity. (These are entirely backward-compatible with the previous return value.)

In addition to the old methods for obtaining data from $modinfo, there are some new functions. For example, here is how to get a single cm_info from $modinfo:

<code php>
$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cmid);
</code>

The cm_info objects contain additional information that is not present in the course_modules database row, such as the module's name, and the icon and associated content mentioned above. In order to distinguish these from the plain database objects, you can specify the cm_info class in a function definition:

<code php>
function my_clever_function(cm_info $cm) {
if (!$cm->uservisible) {
// the module is not visible or available to current user,
// so do something clever instead
}
}
</code>

By specifying cm_info in the parameter list, you'll cause PHP to give an error if anyone tries to call that function with a $cm object that just came from the database row, instead of from <tt>get_fast_modinfo</tt>. (It is good practice to always get $cm from get_fast_modinfo, but there might be exceptions.)

Of course, this is only necessary if your function relies on a feature that is specific to cm_info, such as the 'uservisible' field above. If your function only uses fields which are present in the database row, then there's no need to require cm_info.

== More documentation ==

All three classes for this API are in the core file <tt>lib/modinfolib.php</tt> and contain complete PHPdoc information for all fields and functions.

Development:Module visibility and display

2011-02-16T18:15:33Z

Quen: /* Customising module display, in cache: _get_coursemodule_info */

{{Moodle 2.0}}

The features described here are available since Moodle 2.0.2.

== Summary ==

A new API allows you to customise how your module displays on the main course page:

* You can display custom HTML below the link to your module.

* If your module does not have a link (like Label, where it is only for display on the main page) then you can remove the link from the main page and from all navigation etc.

* You can display HTML next to the link to your module that indicates dynamic information (like Forum, where it displays information about unread messages).

* You can display additional icons next to the other module editing icons when the user is editing the page.

In addition, existing things you could already do (like change the icon on the main page) are still available when using the new API.

The <tt>get_fast_modinfo</tt> function now returns specific classes which are documented and which you can use to obtain new information about modules.

== Backward compatibility ==

All modules and code written for Moodle 2.0 should continue to behave in exactly the same manner. There is no need to change existing modules for this API unless you want to use the new features.

== Removing your link ==

If your module should not appear in navigation and in other lists of modules to visit or get information for, like Label, the easiest way to remove that link is to return true for FEATURE_NO_VIEW_LINK in your module's <tt>_supports</tt> function.

== Customising module display, in cache ==

The first place you can customise your module display is in the existing <tt>_get_coursemodule_info</tt> API function. This function obtains information about the module which will be stored in the course cache (the <tt>modinfo</tt> field of the course table).

The course cache is only updated when somebody edits a module, so it can't be used for dynamic information - but it's okay if it takes a few database queries to calculate the data because it will be cached for future use.

The function should return a value of class <tt>cached_cm_info</tt>. For example:

<code php>
function mod_frog_get_coursemodule_info($cm) {
$info = new cached_cm_info;
$info->content = '<p>This will display below the module.</p>';
return $info;
}
</code>

You can change several properties which are documented in that class definition. If you don't change a property, its value remains default.

* <tt>name</tt> - name of activity (text of the link on course page).
* <tt>icon</tt>, <tt>iconcomponent</tt> - name and component name of icon to display by the link.
* <tt>content</tt> - extra HTML content to display below the module link on course page (not shown in navigation etc).
* <tt>customdata</tt> - arbitrary extra PHP data to store in modinfo cache; useful if, for performance reasons, your module needs to store data that should be accessible very quickly from other parts of the course.
* <tt>extraclasses</tt> - extra CSS class or classes that will be added to the activity on the main page, so that you can alter the styling.
* <tt>onclick</tt> - already-escaped HTML that will be inserted as the value of the onclick attribute.

If you don't need the information to be cached (it can be retrieved very quickly without making any database queries) then you might consider using one of the functions below instead, in order to avoid unnecessarily increasing the size of the course cache. Although the headings mention the current user, you can of course use those functions in a way that doesn't depend on the current user.

== Customising module display, for current user ==

You can customise module display dynamically (when the page loads). For example you might want to alter it based on the permissions of the current user.

<code php>
function mod_frog_cm_info_dynamic(cm_info $cm) {
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
if (!has_capability('some/capability', $context)) {
$cm->set_user_visible(false);
}
}
</code>

This code can affect the navigation, and whether users are permitted to access the module (as above). It runs on all pages within the course, so it's very important that you do not put slow code in this function: it should not make any database queries.

In addition to the <tt>set_user_visible</tt> function shown, you can also set many other things such as additional editing icons which will appear if editing mode is enabled. See the cm_info class documentation for more information.

Most things are set using functions (as above; another example would be <tt>set_content</tt> which sets the same content data as mentioned in the previous section) while other things can be set directly using public variables.

== Customising module display, for current user, on course page only ==

Sometimes you need to display custom information for the current user that appears only on the course view page. For example, the forum module displays unread information on the view page. This information doesn't show on other pages (it isn't included in the navigation, for instance).

<code php>
function mod_frog_cm_info_view(cm_info $cm) {
$cm->set_after_link('Last tadpole: 22:17');
}
</code>

Because this function only runs when looking at the course page:

* It is OK to do tasks which may require some database queries (such as checking for unread forum messages), although obviously this should be kept to a minimum. In particular, care should be taken so that if there are 20 instances of the activity on the course page, it doesn't make 20 separate queries to obtain the information.

* Inside this function you cannot set options which affect the appearance or access to the activity on other pages; for example, you cannot turn off the uservisible flag as shown in the previous example. This is because these options are required on other pages (e.g. to display navigation) so it does not make sense to set them only for the course page. If you try, you'll get a <tt>coding_exception</tt>.

== get_fast_modinfo data ==

The function <tt>get_fast_modinfo</tt> now returns an object of class course_modinfo, which itself contains cm_info objects about each activity. (These are entirely backward-compatible with the previous return value.)

Please see the documentation for more information about these classes. All fields are now documented and there are some new functions. For example, here is how to get a single cm_info from $modinfo:

<code php>
$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cmid);
</code>

The cm_info objects contain additional information that is not present in the course_modules database row, such as the module's name, and the icon and associated content mentioned above. In order to distinguish these from the plain database objects, you can specify the cm_info class in a function definition:

<code php>
function my_clever_function(cm_info $cm) {
if (!$cm->uservisible) {
// the module is not visible or available to current user,
// so do something clever instead
}
}
</code>

By specifying cm_info in the parameter list, you'll cause PHP to give an error if anyone tries to call that function with a $cm object that just came from the database row, instead of from <tt>get_fast_modinfo</tt>. (It is good practice to always get $cm from get_fast_modinfo, but there might be exceptions.)

Of course, this is only necessary if your function relies on a feature that is specific to cm_info, such as the 'uservisible' field above. If your function only uses fields which are present in the database row, then there's no need to require cm_info.

== More documentation ==

All three classes for this API are in the core file <tt>lib/modinfolib.php</tt> and contain complete PHPdoc information for all fields and functions.

Development:Module visibility and display

2011-02-16T18:15:17Z

Quen:

{{Moodle 2.0}}

The features described here are available since Moodle 2.0.2.

== Summary ==

A new API allows you to customise how your module displays on the main course page:

* You can display custom HTML below the link to your module.

* If your module does not have a link (like Label, where it is only for display on the main page) then you can remove the link from the main page and from all navigation etc.

* You can display HTML next to the link to your module that indicates dynamic information (like Forum, where it displays information about unread messages).

* You can display additional icons next to the other module editing icons when the user is editing the page.

In addition, existing things you could already do (like change the icon on the main page) are still available when using the new API.

The <tt>get_fast_modinfo</tt> function now returns specific classes which are documented and which you can use to obtain new information about modules.

== Backward compatibility ==

All modules and code written for Moodle 2.0 should continue to behave in exactly the same manner. There is no need to change existing modules for this API unless you want to use the new features.

== Removing your link ==

If your module should not appear in navigation and in other lists of modules to visit or get information for, like Label, the easiest way to remove that link is to return true for FEATURE_NO_VIEW_LINK in your module's <tt>_supports</tt> function.

== Customising module display, in cache: <tt>_get_coursemodule_info</tt> ==

The first place you can customise your module display is in the existing <tt>_get_coursemodule_info</tt> API function. This function obtains information about the module which will be stored in the course cache (the <tt>modinfo</tt> field of the course table).

The course cache is only updated when somebody edits a module, so it can't be used for dynamic information - but it's okay if it takes a few database queries to calculate the data because it will be cached for future use.

The function should return a value of class <tt>cached_cm_info</tt>. For example:

<code php>
function mod_frog_get_coursemodule_info($cm) {
$info = new cached_cm_info;
$info->content = '<p>This will display below the module.</p>';
return $info;
}
</code>

You can change several properties which are documented in that class definition. If you don't change a property, its value remains default.

* <tt>name</tt> - name of activity (text of the link on course page).
* <tt>icon</tt>, <tt>iconcomponent</tt> - name and component name of icon to display by the link.
* <tt>content</tt> - extra HTML content to display below the module link on course page (not shown in navigation etc).
* <tt>customdata</tt> - arbitrary extra PHP data to store in modinfo cache; useful if, for performance reasons, your module needs to store data that should be accessible very quickly from other parts of the course.
* <tt>extraclasses</tt> - extra CSS class or classes that will be added to the activity on the main page, so that you can alter the styling.
* <tt>onclick</tt> - already-escaped HTML that will be inserted as the value of the onclick attribute.

If you don't need the information to be cached (it can be retrieved very quickly without making any database queries) then you might consider using one of the functions below instead, in order to avoid unnecessarily increasing the size of the course cache. Although the headings mention the current user, you can of course use those functions in a way that doesn't depend on the current user.

== Customising module display, for current user ==

You can customise module display dynamically (when the page loads). For example you might want to alter it based on the permissions of the current user.

<code php>
function mod_frog_cm_info_dynamic(cm_info $cm) {
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
if (!has_capability('some/capability', $context)) {
$cm->set_user_visible(false);
}
}
</code>

This code can affect the navigation, and whether users are permitted to access the module (as above). It runs on all pages within the course, so it's very important that you do not put slow code in this function: it should not make any database queries.

In addition to the <tt>set_user_visible</tt> function shown, you can also set many other things such as additional editing icons which will appear if editing mode is enabled. See the cm_info class documentation for more information.

Most things are set using functions (as above; another example would be <tt>set_content</tt> which sets the same content data as mentioned in the previous section) while other things can be set directly using public variables.

== Customising module display, for current user, on course page only ==

Sometimes you need to display custom information for the current user that appears only on the course view page. For example, the forum module displays unread information on the view page. This information doesn't show on other pages (it isn't included in the navigation, for instance).

<code php>
function mod_frog_cm_info_view(cm_info $cm) {
$cm->set_after_link('Last tadpole: 22:17');
}
</code>

Because this function only runs when looking at the course page:

* It is OK to do tasks which may require some database queries (such as checking for unread forum messages), although obviously this should be kept to a minimum. In particular, care should be taken so that if there are 20 instances of the activity on the course page, it doesn't make 20 separate queries to obtain the information.

* Inside this function you cannot set options which affect the appearance or access to the activity on other pages; for example, you cannot turn off the uservisible flag as shown in the previous example. This is because these options are required on other pages (e.g. to display navigation) so it does not make sense to set them only for the course page. If you try, you'll get a <tt>coding_exception</tt>.

== get_fast_modinfo data ==

The function <tt>get_fast_modinfo</tt> now returns an object of class course_modinfo, which itself contains cm_info objects about each activity. (These are entirely backward-compatible with the previous return value.)

Please see the documentation for more information about these classes. All fields are now documented and there are some new functions. For example, here is how to get a single cm_info from $modinfo:

<code php>
$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cmid);
</code>

The cm_info objects contain additional information that is not present in the course_modules database row, such as the module's name, and the icon and associated content mentioned above. In order to distinguish these from the plain database objects, you can specify the cm_info class in a function definition:

<code php>
function my_clever_function(cm_info $cm) {
if (!$cm->uservisible) {
// the module is not visible or available to current user,
// so do something clever instead
}
}
</code>

By specifying cm_info in the parameter list, you'll cause PHP to give an error if anyone tries to call that function with a $cm object that just came from the database row, instead of from <tt>get_fast_modinfo</tt>. (It is good practice to always get $cm from get_fast_modinfo, but there might be exceptions.)

Of course, this is only necessary if your function relies on a feature that is specific to cm_info, such as the 'uservisible' field above. If your function only uses fields which are present in the database row, then there's no need to require cm_info.

== More documentation ==

All three classes for this API are in the core file <tt>lib/modinfolib.php</tt> and contain complete PHPdoc information for all fields and functions.

Development:Module visibility and display

2011-02-16T18:06:02Z

Quen: /* Removing your link */

{{Moodle 2.0}}

The features described here are available since Moodle 2.0.2.

== Summary ==

A new API allows you to customise how your module displays on the main course page:

* You can display custom HTML below the link to your module.

* If your module does not have a link (like Label, where it is only for display on the main page) then you can remove the link from the main page and from all navigation etc.

* You can display HTML next to the link to your module that indicates dynamic information (like Forum, where it displays information about unread messages).

* You can display additional icons next to the other module editing icons when the user is editing the page.

In addition, existing things you could already do (like change the icon on the main page) are still available when using the new API.

The <tt>get_fast_modinfo</tt> function now returns specific classes which are documented and which you can use to obtain new information about modules.

== Removing your link ==

If your module should not appear in navigation and in other lists of modules to visit or get information for, like Label, the easiest way to remove that link is to return true for FEATURE_NO_VIEW_LINK in your module's <tt>_supports</tt> function.

== Backward compatibility ==

All modules and code written for Moodle 2.0 should continue to behave in exactly the same manner. There is no need to change existing modules for this API.

== Customising module display, in cache: <tt>_get_coursemodule_info</tt> ==

The first place you can customise your module display is in the existing <tt>_get_coursemodule_info</tt> API function. This function obtains information about the module which will be stored in the course cache (the <tt>modinfo</tt> field of the course table).

The course cache is only updated when somebody edits a module, so it can't be used for dynamic information - but it's okay if it takes a few database queries to calculate the data because it will be cached for future use.

The function should return a value of class <tt>cached_cm_info</tt>. For example:

<code php>
function mod_frog_get_coursemodule_info($cm) {
$info = new cached_cm_info;
$info->content = '<p>This will display below the module.</p>';
return $info;
}
</code>

You can change several properties which are documented in that class definition. If you don't change a property, its value remains default.

* <tt>name</tt> - name of activity (text of the link on course page).
* <tt>icon</tt>, <tt>iconcomponent</tt> - name and component name of icon to display by the link.
* <tt>content</tt> - extra HTML content to display below the module link on course page (not shown in navigation etc).
* <tt>customdata</tt> - arbitrary extra PHP data to store in modinfo cache; useful if, for performance reasons, your module needs to store data that should be accessible very quickly from other parts of the course.
* <tt>extraclasses</tt> - extra CSS class or classes that will be added to the activity on the main page, so that you can alter the styling.
* <tt>onclick</tt> - already-escaped HTML that will be inserted as the value of the onclick attribute.

== Customising module display, for current user ==

You can customise module display dynamically (when the page loads). For example you might want to alter it based on the permissions of the current user.

<code php>
function mod_frog_cm_info_dynamic(cm_info $cm) {
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
if (!has_capability('some/capability', $context)) {
$cm->set_user_visible(false);
}
}
</code>

This code can affect the navigation, and whether users are permitted to access the module (as above). It runs on all pages within the course, so it's very important that you do not put slow code in this function: it should not make any database queries.

In addition to the <tt>set_user_visible</tt> function shown, you can also set many other things such as additional editing icons which will appear if editing mode is enabled. See the cm_info class documentation for more information.

Most things are set using functions (as above; another example would be <tt>set_content</tt> which sets the same content data as mentioned in the previous section) while other things can be set directly using public variables.

== Customising module display, for current user, on course page only ==

Sometimes you need to display custom information for the current user that appears only on the course view page. For example, the forum module displays unread information on the view page. This information doesn't show on other pages (it isn't included in the navigation, for instance).

<code php>
function mod_frog_cm_info_view(cm_info $cm) {
$cm->set_after_link('Last tadpole: 22:17');
}
</code>

Because this function only runs when looking at the course page:

* It is OK to do tasks which may require some database queries (such as checking for unread forum messages), although obviously this should be kept to a minimum. In particular, care should be taken so that if there are 20 instances of the activity on the course page, it doesn't make 20 separate queries to obtain the information.

* Inside this function you cannot set options which affect the appearance or access to the activity on other pages; for example, you cannot turn off the uservisible flag as shown in the previous example. This is because these options are required on other pages (e.g. to display navigation) so it does not make sense to set them only for the course page. If you try, you'll get a <tt>coding_exception</tt>.

Development:Module visibility and display

2011-02-16T18:05:39Z

Quen: /* Summary */

{{Moodle 2.0}}

The features described here are available since Moodle 2.0.2.

== Summary ==

A new API allows you to customise how your module displays on the main course page:

* You can display custom HTML below the link to your module.

* If your module does not have a link (like Label, where it is only for display on the main page) then you can remove the link from the main page and from all navigation etc.

* You can display HTML next to the link to your module that indicates dynamic information (like Forum, where it displays information about unread messages).

* You can display additional icons next to the other module editing icons when the user is editing the page.

In addition, existing things you could already do (like change the icon on the main page) are still available when using the new API.

The <tt>get_fast_modinfo</tt> function now returns specific classes which are documented and which you can use to obtain new information about modules.

== Removing your link ==

If your module should not have a link in navigation etc., like Label, the easiest way to remove that link is to return true for FEATURE_NO_VIEW_LINK in your module's <tt>_supports</tt> function.

== Backward compatibility ==

All modules and code written for Moodle 2.0 should continue to behave in exactly the same manner. There is no need to change existing modules for this API.

== Customising module display, in cache: <tt>_get_coursemodule_info</tt> ==

The first place you can customise your module display is in the existing <tt>_get_coursemodule_info</tt> API function. This function obtains information about the module which will be stored in the course cache (the <tt>modinfo</tt> field of the course table).

The course cache is only updated when somebody edits a module, so it can't be used for dynamic information - but it's okay if it takes a few database queries to calculate the data because it will be cached for future use.

The function should return a value of class <tt>cached_cm_info</tt>. For example:

<code php>
function mod_frog_get_coursemodule_info($cm) {
$info = new cached_cm_info;
$info->content = '<p>This will display below the module.</p>';
return $info;
}
</code>

You can change several properties which are documented in that class definition. If you don't change a property, its value remains default.

* <tt>name</tt> - name of activity (text of the link on course page).
* <tt>icon</tt>, <tt>iconcomponent</tt> - name and component name of icon to display by the link.
* <tt>content</tt> - extra HTML content to display below the module link on course page (not shown in navigation etc).
* <tt>customdata</tt> - arbitrary extra PHP data to store in modinfo cache; useful if, for performance reasons, your module needs to store data that should be accessible very quickly from other parts of the course.
* <tt>extraclasses</tt> - extra CSS class or classes that will be added to the activity on the main page, so that you can alter the styling.
* <tt>onclick</tt> - already-escaped HTML that will be inserted as the value of the onclick attribute.

== Customising module display, for current user ==

You can customise module display dynamically (when the page loads). For example you might want to alter it based on the permissions of the current user.

<code php>
function mod_frog_cm_info_dynamic(cm_info $cm) {
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
if (!has_capability('some/capability', $context)) {
$cm->set_user_visible(false);
}
}
</code>

This code can affect the navigation, and whether users are permitted to access the module (as above). It runs on all pages within the course, so it's very important that you do not put slow code in this function: it should not make any database queries.

In addition to the <tt>set_user_visible</tt> function shown, you can also set many other things such as additional editing icons which will appear if editing mode is enabled. See the cm_info class documentation for more information.

Most things are set using functions (as above; another example would be <tt>set_content</tt> which sets the same content data as mentioned in the previous section) while other things can be set directly using public variables.

== Customising module display, for current user, on course page only ==

Sometimes you need to display custom information for the current user that appears only on the course view page. For example, the forum module displays unread information on the view page. This information doesn't show on other pages (it isn't included in the navigation, for instance).

<code php>
function mod_frog_cm_info_view(cm_info $cm) {
$cm->set_after_link('Last tadpole: 22:17');
}
</code>

Because this function only runs when looking at the course page:

* It is OK to do tasks which may require some database queries (such as checking for unread forum messages), although obviously this should be kept to a minimum. In particular, care should be taken so that if there are 20 instances of the activity on the course page, it doesn't make 20 separate queries to obtain the information.

* Inside this function you cannot set options which affect the appearance or access to the activity on other pages; for example, you cannot turn off the uservisible flag as shown in the previous example. This is because these options are required on other pages (e.g. to display navigation) so it does not make sense to set them only for the course page. If you try, you'll get a <tt>coding_exception</tt>.

Development:Module visibility and display

2011-02-16T18:03:45Z

Quen: /* Customising module display, in course cache: _get_coursemodule_info */

Development:Module visibility and display

2011-02-16T17:44:11Z

Quen: /* Customising module display, in course cache: _get_coursemodule_info */

Development:Module visibility and display

2011-02-16T17:43:55Z

Quen:

Development:Using the File API in Moodle forms

2011-02-11T17:23:47Z

Quen: /* Convert internal relative links to absolute links */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'accepted_types' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Using the File API in Moodle forms

2011-02-11T17:23:20Z

Quen: /* Convert internal relative links to absolute links */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'accepted_types' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; "$context->id/component/proper_file_area/$itemid/" : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Using the File API in Moodle forms

2011-02-11T17:23:05Z

Quen: /* Convert internal relative links to absolute links */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[Development:File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[Development:lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Development:Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[Development:File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Development:Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'accepted_types' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 0) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/file/file_types.mm moodle/lib/file/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_moymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; "$context->id/component/proper_file_area/$itemid/" : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[Development:File API]]
* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Development:Migrating contrib code to 2.0

2011-02-02T12:21:19Z

Quen: /* Backup and Restore */

{{stub}}

{{Moodle 2.0}}

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

== Installation ==

The 'requires' version in the plugin's version.php is checked to make sure it looks like Moodle 2.0. You should change this value to '2010112400' or later otherwise plugin installation will abort.

== Database ==
* [[Development:DB_layer_2.0_migration_docs]]

== File system ==

== Forms API ==
* [[Development:Using the File API in Moodle forms]]
* [[Development:Using_the_file_API]]

== Themes ==
* [[Development:Output_renderers]]
* [[Development:Text formats 2.0|Text formats 2.0]] how user-entered content is handled.
* [[Development:Migrating_your_code_to_the_2.0_rendering_API]] (n.b., some info outdated and may need updating)
* [[Development:Themes_2.0]]

Some details of how to re-design image CSS for plugin code are in the main themes documentation: [[Development:Themes_2.0_creating_your_first_theme#Using_images_within_CSS]]

Be aware that themes are now cached on the server and so emptying your browser cache will not refresh the CSS. This can only be done by going to the site administration->appearance->themes->theme selector page and clicking the 'invalidate theme caches' button.

== JavaScript ==
JavaScript is included in different ways now and will need to be migrated, see the PHPDoc comments in /lib/outputrequirements.lib and some (slightly outdated) advice here: [[Development:JavaScript_guidelines]]

== Backup and Restore ==

* [[Development:Backup_2.0_for_developers]]
* [[Development:Restore_2.0_for_developers]]

== Miscellaneous ==
There are other coding changes such as:
* MDL-24063 which eliminates PARAM_CLEAN
* MDL-24058 about no longer using stripslashes or addslashes
* [[Deprecated_functions_in_2.0]]

Please feel free to add others that come to mind. CONTRIB maintainers should check their 2.0 versions for these and make sure that they are appropriately handled.

== See also ==

* [[Moodle_2.0_release_notes]]
* CONTRIB-1988
* http://cvs.moodle.org/moodle/blocks/upgrade.txt?view=markup
* http://cvs.moodle.org/moodle/mod/upgrade.txt?view=markup
* [[User:Frank_Ralf/Experience_of_converting_a_module_to_Moodle_2|Experience of converting a module to Moodle 2]] by Sam Marshall (perhaps that documentation should better live here? --[[User:Frank Ralf|Frank Ralf]] 16:36, 15 November 2010 (UTC))
* [[Development:Local_customisation]]
* [[Development:Migrating to 2.0 checklist]] list of things to look out for when upgrading a plug-in

[[Category:Developer]]

Development:Migrating contrib code to 2.0

2011-02-02T12:05:55Z

Quen: /* Backup and Restore */

{{stub}}

{{Moodle 2.0}}

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

== Installation ==

The 'requires' version in the plugin's version.php is checked to make sure it looks like Moodle 2.0. You should change this value to '2010112400' or later otherwise plugin installation will abort.

== Database ==
* [[Development:DB_layer_2.0_migration_docs]]

== File system ==

== Forms API ==
* [[Development:Using the File API in Moodle forms]]
* [[Development:Using_the_file_API]]

== Themes ==
* [[Development:Output_renderers]]
* [[Development:Text formats 2.0|Text formats 2.0]] how user-entered content is handled.
* [[Development:Migrating_your_code_to_the_2.0_rendering_API]] (n.b., some info outdated and may need updating)
* [[Development:Themes_2.0]]

Some details of how to re-design image CSS for plugin code are in the main themes documentation: [[Development:Themes_2.0_creating_your_first_theme#Using_images_within_CSS]]

Be aware that themes are now cached on the server and so emptying your browser cache will not refresh the CSS. This can only be done by going to the site administration->appearance->themes->theme selector page and clicking the 'invalidate theme caches' button.

== JavaScript ==
JavaScript is included in different ways now and will need to be migrated, see the PHPDoc comments in /lib/outputrequirements.lib and some (slightly outdated) advice here: [[Development:JavaScript_guidelines]]

== Backup and Restore ==

* [[Development:Backup_2.0_for_developers]]

== Miscellaneous ==
There are other coding changes such as:
* MDL-24063 which eliminates PARAM_CLEAN
* MDL-24058 about no longer using stripslashes or addslashes
* [[Deprecated_functions_in_2.0]]

Please feel free to add others that come to mind. CONTRIB maintainers should check their 2.0 versions for these and make sure that they are appropriately handled.

== See also ==

* [[Moodle_2.0_release_notes]]
* CONTRIB-1988
* http://cvs.moodle.org/moodle/blocks/upgrade.txt?view=markup
* http://cvs.moodle.org/moodle/mod/upgrade.txt?view=markup
* [[User:Frank_Ralf/Experience_of_converting_a_module_to_Moodle_2|Experience of converting a module to Moodle 2]] by Sam Marshall (perhaps that documentation should better live here? --[[User:Frank Ralf|Frank Ralf]] 16:36, 15 November 2010 (UTC))
* [[Development:Local_customisation]]
* [[Development:Migrating to 2.0 checklist]] list of things to look out for when upgrading a plug-in

[[Category:Developer]]

Development:Module visibility and display

2011-01-14T12:13:07Z

Quen: /* course_modinfo */

This document is '''only a proposal'''. The functionality described doesn't exist yet in Moodle.

== DRAFT 2 ==

This is the second draft of the proposal, with changes based on Petr's comments. As well as/because of adding all the class stuff, this version no longer requires rebuild_course_cache and should be 100% backward compatible with all existing uses of modinfo.

Notes:

* Petr wanted dynamic/lazy computation of some of the access stuff - this is necessary for the forum unread data etc, but not feasible to do in this version for any of the data that is already included in modinfo, because of the requirement for 100% BC which is not possible with __get methods; so all the existing property values must be initialised (see below). This also means it's a less scary change, i.e. more moving code around and less new code.

* I wanted a class for the overall thing, which I called course_modinfo (because it's basically from the modinfo field of the course table). Then I neeed a name for the class for an individual module instance info. Petr suggested module_info but I thought cm_info was a bit closer (module_info might sound like it was about a whole module, not one instance). Anyhow, both names subject to change if anyone has better suggestions.

* Linking the cm_info to its parent course_modinfo gives a nice framework to do caching/lazy-initialisation stuff. For instance when we calculate forum unread data in the mod_forum_cm_info_view function, we will get a request for a single $cminfo, but can actually retrieve the data for all forum instances on the course at once (same as at present).

* I didn't specify exactly how to address modinfo caching issues (...if there are any) but because this proposal suggests moving the 'work out the values' stuff into the class, and leaving get_fast_modinfo to deal only with caching, it should be a whole lot simpler to see how the caching works and alter it in future.

== Summary ==

We would like to create a generic API that allows the following:

* Module display on front page can be customised, for example making it possible to create another module that behaves like Label (displaying arbitrary html rather than a link to activity view.php) - currently this is hardcoded hack for Label. This change should apply to other areas such as navigation block as well as course page.

* Some modules can provide dynamic text, such as forum displaying unread messages. At present this is hardcoded so that only forum can do it.

* Modules can be hidden completely, or greyed out, from the view of particular students according to either custom module behaviour, or (if not specified by module) default behaviour regarding a new capability moodle/course:viewactivity and the existing option for whether a non-available module is greyed out or hidden entirely.

This should take advantage of the existing modinfo cache in order that performance is not adversely affected.

== API improvement ==

Following Petr's suggestions, we would also like to improve the API by switching the modinfo in-memory data structures to use defined classes instead of anonymous stdClass objects. This achieves the following:

* Provides a location for documentation of these structures. (Currently they are undocumented.)

* In future, allows functions to specify the required type (i.e. some functions require the information from modinfo, not just a row from the table; they will now be able to specify this). There is no plan to change function definitions immediately.

* Where the type is defined, makes metadata available to IDEs, allowing code completion and automatic documentation viewing.

The following requirements should also be met:

* 100% backward compatibility for existing use of these structures by core and third-party modules. (Obviously, where these want to support the new features, such as the navigation supporting other label-like modules, there do need to be changes which are included in these patch. But if we forget something or it's third-party, it should keep working as at present.)

* 100% backward compatibility for existing modinfo data (in database).

== Removing existing hacks ==

* Existing hacks regarding label in all areas of code (e.g. navigation, etc) will be changed from the logic 'is this a label?' to the logic 'does this activity have a view page?' (which will work for label too)
* Existing hacks regarding forum unread data will be removed and the forum unread code will be moved into the new API function. The code will be written in such a way as to have the same performance characteristics.

== get_fast_modinfo change ==

The get_fast_modinfo function will be changed to return a new object of type course_modinfo, which will be compatible with the existing $modinfo return value.

While constructing this object, in addition to current behaviour, the system will:

* support new values defined in _get_coursemodule_info

* extend dynamic per-user calculation (that checks is something is visible to current user, ->uservisible) with additional checks

* call the new module API (if provided) after calculating modinfo, to get dynamic information

== course_modinfo ==

The new class course_modinfo will contain properties:

* courseid, userid (ints)
* sections (array of int => array of int)
* cms (array of int => cm_info)
* instances (array of string => array of int => cm_info)
* groups - groups that the current user belongs to - loaded only if needed i.e. if there are activities that are groupmembersonly, otherwise null

These are identical to the values currently returned by modinfo, except for the use of cm_info class instead of bare stdClass for the information about modules.

There are three options for handling this class:

# Make these properties public so that they can be accessed exactly as at present.
# Make them private and use PHP magic __set and __get functions so that they can be read as normal but any attempt to write them would (while working) also cause a developer debug warning.
# Make the properties public, but deprecate them, and create separate get methods (get_courseid, get_userid, etc) which are recommended for future use.

I initially favoured the second option but unfortunately, PHP being PHP, this doesn't quite work properly: specifically, you can't use the empty() function on such values. Since there might be places in the code that call empty(), maybe this isn't a good idea.

Consequently I tend to the third one; we should make better get methods such as get_cm($cmid) as well as just get_cms(), which may help make new code more readable.

=== Construction ===

The code that creates this information should largely be moved to this class (either in a constructor or in init methods etc) from its current location in get_fast_modinfo. get_fast_modinfo should remain responsible only for caching these objects.

== cm_info class ==

=== Basic structure ===

The new class cm_info will be constructed with a $parent (course_modinfo). Knowing its parent allows the class to carry out operations with regard to the whole course, where this is beneficial for performance, without needing extra parameters. There will be a get_modinfo() method to return this.

=== Defined states ===

This class has three states:

* BASIC_DATA: class has the data from database modinfo table, and automatically completed data that is not related to the current user.
* DYNAMIC_DATA: class has all data that is available for most pages, including data related to the current request from the current user's permissions and the _cm_info_dynamic function if applicable.
* VIEW_DATA: class also has the data that is needed only on the course view page (or similar pages) from the _cm_info_view function if applicable (basically only used for forum unread data and stuff like that).

When get_fast_modinfo returns, all returned objects will be in DYNAMIC_DATA state. This will be sufficient for determining whether the current user has access to the activity and for displaying the basic link etc. Basically the only thing it doesn't include is supplemental data that is only needed on the course page, such as forum unread data (get_after_link function). This data takes time to calculate so is generated on request.

The intention is that getting to DYNAMIC_DATA state shouldn't require any database calls (certainly for the core modules). Getting to VIEW_DATA state may require database calls, e.g. to calculate the number of unread forum posts.

=== Existing properties ===

These properties are in current modinfo:

* id, instance, course, idnumber, visible, groupmode, groupingid, groupmembersonly, indent, completion, availablefrom, availableuntil, showavailability - data from course_modules row

* extra, icon, iconcomponent, modname, name, sectionnum, conditionscompletion, conditionsgrade, modplural (wtf is this there when the singular name isn't and both should be available with get_string?!) - data from modinfo which was computed when generating the cache

* availableinfo, available, uservisible - data relating to the current user which is computed dynamically when obtaining the modinfo object

This is the list of properties currently available in modinfo objects, so will be implemented as-is. The same question regarding use of __set, __get applies as above, but in this case it's perhaps more likely that people might call empty() on the existing properties; again, I propose retaining the above as public properties, but deprecated, and providing get_x methods for new use. Any new properties would be private and available only with get_ methods.

Some of the get methods might have a slightly different definition to the raw properties. For example get_icon should use the provided data to return a moodle_icon object (if there is one? I am not sure), not a string.

=== New data / get methods ===

The new data and corresponding get methods are:

* has_view() - true if the module should have a link to its view.php shown in navigation, be included in lists of 'did the user visit this module' stats, etc. (Basically this is the 'is not a label' method.)
* get_url() - returns moodle_url to module view.php, or null if has_view is false (this reduces code duplication in various places)
* get_content() # - returns HTML content to be displayed on the course page where this module is placed; appears below the link, if present (this is how Label displays content on course page)
* get_extra_classes() # - returns additional CSS classes to be added to the A or DIV tag(s) for this item on main course page.
* get_custom_data() - returns an optional mixed value containing custom data for this module, which needs to be available course-wide via the get_fast_modinfo function.
* get_after_link() # - returns HTML code which displays after the link.
* get_after_edit_icons() # - returns HTML code which displays after the standard icons (hide, edit, delete, etc) when editing.

Functions marked # require 'view information'. This is additional information intended for use on the course view page and not in other places that use modinfo: the most obvious example (and the only one that affects core) is forum unread data. Consequently it is only obtained on request (see state information above). Obtaining view info requires calling the module's _cm_info_view function if it has one.

=== Set methods ===

Set methods are available for use only by _cm_info_dynamic and _cm_info_view functions; see below.

== Modify _get_coursemodule_info ==

There will be a change to the existing module API function _get_coursemodule_info which is used to update information before storing it in the database modinfo field. This change will retain backward compatibility.

The function returns an object which is currently a stdClass object. This possibility will be retained for backward compatibility, with unchanged behaviour. All existing fields are supported:

* name: name of instance or (for labels only) content of instance
* icon: name of icon or special weird string
* iconcomponent: component of icon, possibly works
* extra: extra data inserted somewhere horrible in the html

These fields are all optional and may be left unset to accept the defaults.

However a new class cached_cm_info can be returned instead.

The class cached_cm_info has the following properties:

* name, icon, iconcomponent: as before
* content: HTML content to be displayed on the course page where this module is placed; appears below the link, if present (this is how a Label-like module can display content on course page)
* customdata: A place to store a string or object containing custom data for this module, which needs to be available course-wide via the get_fast_modinfo function. If present, this data should be small in size.
* extraclasses: Extra CSS classes to add to the item on course page display, if required.

(It does not support extra, which is deprecated on account of being stupid, at least unless I figure out some existing use case that really needs to be carried forward into a non-deprecated system.)

=== Storing data ===

Returning a stdClass object should result in identical content of the modinfo field in the database to present.

Return cached_cm_info results in similar content but with extra fields ->content and ->customdata. These fields are only stored if they are non-null, i.e. it won't bulk up the database with empty 'content=nothing' type data against every module.

=== Reading label data ===

The new content field is different to existing behaviour of the Label module, which stores its content in the 'name' field as noted. When reading this data or processing it (for example in cm_info class), the system takes the following approach:

* if the modname is 'label' and there is no 'content' field, then copy the 'name' field into 'content'.

Note that this behaviour retains backward compatibility; the label still has a silly 'name' value. For new code, has_view() returns false so it won't use name; for old code, the existing hard-coded exceptions for label will continue to work.

== Extend dynamic calculation ==

Currently the modinfo code makes the following checks that apply dynamically per-request (and do not directly come from the cache) in order to create the ->uservisible member variable.

* If ->groupmembersonly is set, checks if the user belongs to group or has accessallgroups.
* If availability restrictions (date, grade, completion) are set, checks these (also even if available to current user, stores information into ->availableinfo, ->available for information when editing).

My proposal is:

* Make this part of the code (that 'specialises' a single mod value for the current user/request) into a separate function within cm_info class, just to simplify it. This function should be the one that changes the cm_info state from BASIC_DATA to DYNAMIC_DATA.
* Add a check for the moodle/course:viewactivity capability; if user doesn't have this capability, set ->uservisible to false. Also check the option about what to do with hidden activities; if this is set to the default 'grey it out', then set ->inactive to true.
** Note: The default value for moodle/course:viewactivity should be true for all roles, even guest. This maintains existing behaviour. Sites that don't want guests to view activities can change the main role definition for guest.
* Call the _cm_info_dynamic function (below) if the current module supplies one.

PERFORMANCE CONCERNS: Minimal. No new database queries are required, just a capability check and a function existence check.

== New module API ==

Two new module API functions will be defined. They both have one parameter: the cm_info object for this module, containing all the data from the modinfo cache.

The functions are:

* _cm_info_dynamic - add basic data that is always required (must be fast; should not make any database calls)
* _cm_info_view - add data that is required for the course view page (may make database calls)

The functions both call set methods in the cm_info object. Examples:

* set_user_visible(false) - hide activity entirely
* set_available(false) - grey out activity while it remains visible
* set_available_info('not available because you suck') - add explanation for why it's not available
* '''set_after_link'''('16 unread') # - add html code to appear after link
* '''set_edit_icons'''($html) # - add some code to appear when editing
* set_has_view(false) - make module not have link, navigation, etc even if it has a view.php
* set_content($html) # - add/change code to appear below the link
* set_name($text) - change text of the link
* set_extra_classes('whatever classes') # - add CSS classes

The bold functions set cm_info data that cannot be set anywhere else (such as by system defaults or modinfo classes). This is basically because there didn't seem any general need to cache this data, particularly bearing in mind that modules can cache anything they like using the customdata property of cached_cm_info.

_cm_info_view is restricted: for example, you cannot change user_visible status in view (because then it wouldn't work when checking access etc on other pages). You can only change the 'view' properties. This can be enforced by making the set methods throw exceptions if called when the cm_info is in its already-defined state.

Should it be necessary, this function can access the existing information in the cm_info object and also in the parent course_modinfo object (such as the user id) by calling get_modinfo on the cm_info.

PERFORMANCE CONCERNS: None. Of standard modules, only the forum will implement this and only in the 'view' version used just on course page; it will use the same code as at present. Custom modules will need to be written carefully in a similar manner so that they also perform well (ie do any queries once for whole course and store in global cache, not once per module).

== Access permissions ==

When calling require_login with a $cm parameter, this will do get_fast_modinfo and check the is_user_visible() method in order to process per-user access restrictions:

* groupmembersonly
* moodle/course:viewactivity

PERFORMANCE CONCERNS: Because require_login like this is used on all module pages, we should use a profiler to evaluate before/after performance of this change and ensure that it isn't worsened. I suspect it won't be, because I think it already checks groupmembersonly anyway, so it's doing basically the same test; and I think most pages already call get_fast_modinfo e.g. for navigation block.

NOTE: The way modules currently initialise is a bit inefficient, if get_fast_modinfo is to be used. The current sequence on most module pages is something like:

* get course module (from id, supplied)
* get course
* get instance

(3 queries)

we could change this to

* get course (from simple join using cmid, supplied)
* use get_fast_modinfo to get cm
* get instance

(2 queries)

Not suggesting that as part of this change (and it probably shouldn't be in this document), just saying...

Development talk:Coding style

2011-01-13T17:46:01Z

Quen: /* Database code */ new section

== PHP5 constructor ==

Should we enforce the PHP5 constructor __construct() instead of $classname() [[User:Nicolas Connault|Nicolas Connault]] 19:55, 19 May 2009 (UTC)
:+1. I think we agreed about that some time ago (when igniting some 2.0 developments) --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:03, 20 May 2009 (UTC)

== Inline comments ==

I have been using since ages ago "///" with outer alignment (I think that it was caused by some agreement long time ago, not my decision), for example:

<code php>
function check_moodle_environment(..., ..., ..., ...) {

$status = true;

/// This are cached per request
static $result = true;
static $env_results;
static $cache_exists = false;

/// if we have results cached, use them
if ($cache_exists) {
$environment_results = $env_results;
/// No cache exists, calculate everything
} else {
/// Get the more recent version before the requested
if (!$version = get_latest_version_available($version, $env_select)) {
$status = false;
}
....
....
</code>
Is that allowed, or only the "//" with inner alignment as commented at [[Development:Coding style#Inline comments|inline comments]] --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 00:03, 20 May 2009 (UTC)

I did start doing all mine this way, but if you look at the code it seems you and I are the only ones. :P It seems sensible to make the standard fit what most people are used to (and how most of the code looks).
-- [[User:Martin Dougiamas|Martin Dougiamas]] 06:02, 9 June 2009 (UTC)

Eloy and Martin, this the only thing which consistently offends me about moodle coding style! Please go inline like all the cool kids ;-) --[[User:Dan Poltawski|Dan Poltawski]] 00:15, 12 June 2009 (UTC)

LOL. +1 for inline in even lines + out in odd one :-P
(seriously np with inline at all, it's only one habit easily modifiable) --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 01:03, 12 June 2009 (UTC)

==Trailing spaces==

"Lines should not contain trailing spaces. In order to facilitate this convention, most editors can be configured to strip trailing spaces, such as upon a save operation. However, if you are editing an existing Moodle file and are planning to submit your changes to CVS, please switch off that feature so that whitespace changes do not pollute CVS history (other developers will have trouble viewing what you've done if every other line has been edited for whitespace)."
Wouldn't the CVS history only get 'polluted' when someone fetched a file that DIDN'T follow this principle and returned it following the principle? Isn't that the price that has to be paid to clean things up? Otherwise this is pretty scary for someone who feels: "Great I can turn on my editor to autostrip those when saving. BUT I have to remember to turn that off if submitting it! (Or become a 'polluter'!)"
And what happens if I have already saved it locally while working on (and striped those trailing spaces) and later try to commit it. Maybe my ignorance about CVS is making me pose a "silly" question. [[User:Jeff Forssell|Jeff Forssell]] 07:17, 27 May 2009 (UTC)

: Jeff, the point with coding guidelines is that all new code must follow all the guidelines. With old bad code, mostly it is better to make the smallest change necessary when, for example, you fix a bug. That makes it clearest what the purpose of your change was. However, any line you do change while fixing the bug, you can then improve the coding style on that line.

: Really good editors actually have an option "Strip trailing whitespace when saving a file - but only from lines that I have edited", which is what you really want.

: The real way to avoid being a CVS polluter is to follow the best practice and always do a cvs diff and review all your changes (and if necessary amend them) before you do a CVS commit.--[[User:Tim Hunt|Tim Hunt]] 03:52, 1 June 2009 (UTC)

=== Breaking up lines (e.g. huge arrays) ===

The coding style says to align the start of the following lines with the element in the first.. e.g.

<code php>
$myarray = array( 'fred' => 'blue',
'tom' => 'green' );
</code>

I have to say I don't like this. While it looks very pretty it is a code maintenance nightmare. If you change (say) the array name you have to change every other line just to keep it looking nice. Surely if you '''must''' have it looking like this, do this...

<code php>
$myarray = array(
'fred' => 'blue',
'tom' => 'green' );
</code>

It's the same issue with long lists of assignments - making all the RHSs line up. Completely unnecessary and just asking for errors. Don't encourage people to change code that they don't have to. If they don't touch it then they can't break it. --[[User:Howard Miller|Howard Miller]] 13:52, 1 June 2009 (UTC)

:Agree 100% with Howard, I prefer the 2nd alternative for sure, if not always, at least in places where indentation is already considerable. BTW, same for harcoded SQLs and other strings. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 13:58, 1 June 2009 (UTC)

: +1 from me too for a fixed indent for follow-on lines. Actually I have always used 8-spaces (double the normal indent) ever since I started programming in Java and read their docing guidelines. I think it is helpful to have a different level of indent for a follow-on line and a block.

: Sure, makes sense. I've fixed the docs. The only exception IMO would be wrapping function parameters, which just look too wierd to me if you wrap them the same as arrays. See [https://docs.moodle.org/en/Development:Coding_style#Wrapping_function_declarations the example]. -- [[User:Martin Dougiamas|Martin Dougiamas]] 06:08, 9 June 2009 (UTC)

: At the expense of some white space...

<code php>
public function graded_users_iterator(
$course,
$grade_items = null,
$groupid = 0,
$sortfield1 = 'lastname',
$sortorder1 = 'ASC',
$sortfield2 = 'firstname',
$sortorder2 = 'ASC') {
</code>

: There is an argument that a function is badly thought out if it needs line after line of parameters. Won't go there though :-) --[[User:Howard Miller|Howard Miller]] 09:51, 23 June 2009 (UTC)

== Function and method declaration ==

[[Development:Coding_style#Function_and_method_declaration]] says "Don't leave spaces between the function name and the opening parenthesis for the arguments." and yet the example below it completely disregards it. Please fix it. --[[User:Kumaraguru G|Kumaraguru G]] 21:32, 4 July 2009 (UTC)
: Hi, Kumaraguru. This is a wiki so you can just do it yourself ;-) --[[User:Frank Ralf|Frank Ralf]] 21:45, 4 July 2009 (UTC)
::Hi Frank, the page is protected and I don't have edit access :) --[[User:Kumaraguru G|Kumaraguru G]] 00:30, 5 July 2009 (UTC)
:::: Oops, sorry, totally forgot about that. --[[User:Frank Ralf|Frank Ralf]] 06:11, 6 July 2009 (UTC)
:::I just fixed that, and a few other things I noticed.--[[User:Tim Hunt|Tim Hunt]] 03:13, 5 July 2009 (UTC)

== Running empty lines ==

I propose to allow only single empty line as a separator. We can get rid of running empty lines at once using

for file in `find . -name "*.php"`; do cat -s $file > /tmp/cat.php && cat /tmp/cat.php > $file ; done;

If agreed, the fix of the template for the beginning of a file is needed.
--[[User:David Mudrak|David Mudrak]] 15:25, 18 July 2009 (UTC)

: I use a single line everywhere, except that I use two blank lines between classes. I don't think we need to make a big deal about this.--[[User:Tim Hunt|Tim Hunt]] 09:42, 19 July 2009 (UTC)

== File comments ==

1. About packages. I think what is there is OK. Separate packages for moodlecore and plugs. However, I don't think it is sufficient. There are some parts of the code (I am thinking of question) that are relatively self-contained. I think it is silly to put them all in moodlecore. I would rather use packages questionbank and questionengine. Is that OK. If so, can someone (I am happy to) add this to the docs. message, notes and comments may be other good candidates for separate packages. Also course and user.--[[User:Tim Hunt|Tim Hunt]] 10:10, 2 October 2009 (UTC)

: [[User:Martin Dougiamas|Martin Dougiamas]] 06:31, 5 October 2009 (UTC): The problem is that we don't want to have hundreds of packages in the list at the top of http://phpdocs.moodle.org/HEAD/index.html so this has to be controlled. In fact we already have all the ones you mentioned there ... there seems to be some confusion with different guesses/versions at what the name should be (group/groups is one example). I'm against courses and users because functions for these are in many different mixed files. We have the new Moodle API externallib.php files in 2.0 which will really list all the main functions people would need. Frankly it's a mess and I think trying to add lots more distinction makes it worse... The main thing we were trying to do was separate core from modules.

:: I disagree. It is stupid to worry about the list of packages being so long that it is difficult to understand if, once you get into a particular package, the list of stuff in there is so long it is completely incomprehensible. The whole point of packages is to break the codebase up into manageable and relatively independent chunks to help people understand it.

:: Really, the problem here is that the PHPdocumentor template we are using is not up to the job of displaying a project as big as Moodle. We should use a template more like the JavaDoc on (http://java.sun.com/javase/6/docs/api/). That scales much better. Job for Jordan?

:: And it would make sense to ensure that all the core packages were listed together. Perhpas we should adopt a convention like core-question-bank and core-question-engine for core sub-packages. I agree that too many packages would still be a mistake, but so is too few.--[[User:Tim Hunt|Tim Hunt]] 08:37, 5 October 2009 (UTC)

::: [[User:Martin Dougiamas|Martin Dougiamas]] 12:58, 5 October 2009 (UTC): Isn't that what we have subpackages for? We're using them that way all over the place already (eg see blog and deprecated etc under moodlecore). That makes more sense to me than going for long names. At least for now. A lot of core functions are not as easy to separate as questions might be, and if we do it for some and not others then we have to explain that decision-making process too ...

:::: [[User:Tim Hunt|Tim Hunt]] 20:32, 5 October 2009 (UTC) OK. I am happy to use subpackages. I'll follow those two examples.

2. The OU likes me to put

* @copyright © 2006 The Open University

which is fair enough. In this case, I think it would make sense to add an extra

* @author ...

tag, even though in other cases we don't require them.--[[User:Tim Hunt|Tim Hunt]] 10:10, 2 October 2009 (UTC)

: [[User:Martin Dougiamas|Martin Dougiamas]] 06:31, 5 October 2009 (UTC): Sorry but I totally disagree this should be in a @author tag at all. You are probably not the sole author in the first place, and others will edit them in future and think they have to start adding their own name to any file they touch. It gets contentious. That's why we pulled them all out in the first place. CVS has full author information for every line, no need to put it in the file. You can put your name in the comments at the top of you like (something like "Initially written by Tim Hunt").

:: Ah, fair enough. I was forgetting that the purpose of that like was just to make the copyright owner clear. I completely agree with you about not duplicating information in CVS.--[[User:Tim Hunt|Tim Hunt]] 08:37, 5 October 2009 (UTC)

I just updated the bit about @package names, following discussion and a clear consensus with Petr: http://moodle.org/mod/cvsadmin/view.php?conversationid=4294.--[[User:Tim Hunt|Tim Hunt]] 10:47, 3 March 2010 (UTC)

== Wrapping Control Structures ==

The example given suggests that:
<code php>
if (f() and g()) {

}
</code>
is equivalent to:
<code php>
$tmp1 = f();
$tmp2 = g();
if ($tmp1 and $tmp2){

}
</code>

But in the former g() is evaluated only if f() returns a value that is true (in a boolean context).

I suggest something like

BETTER GOOD:
<code php>
$coursecategory = $element['object']->is_course_item() or $element['object']->is_category_item();
if ($coursecategory) {
$scalevalue = in_array($element['object']->gradetype, array(GRADE_TYPE_SCALE, GRADE_TYPE_VALUE));
if ($scalevalue){
</code>

I also suggest that the code fragments in GOOD and BAD be made to agree in the rest of the logic. (GOOD has form ((a or b) and c) while BAD has form ((a or b) and (c or d)).

[[User:jfine]] 7.35, 1 Aug 2010 (UTC)

== Sensible temporaries ==

Here's some code thought to be BAD, improved with temporaries (and a probably trivial change of meaning).
<code php>
$eo = element['object'];
$eog = $eo->gradetype;

if (($eo->is_course_item() or $eo->is_category_item())
and ($eog == GRADE_TYPE_SCALE or $eog == GRADE_TYPE_VALUE)) {
</code>

There. The BAD code is now not so bad after all. [[User:jfine]] 00:76, 1 Aug 2010 (UTC)

== Database code ==

I would suggest the following database coding guidelines

== Database code using SQL ==

* Where possible, use the plain get_records, get_recordset, etc functions instead of the _sql variants.

Correct:

$DB->get_record('course', array('id' => $id));

Wrong:

$DB->get_record_sql('SELECT * FROM {course} WHERE id=?', array($id));

* When using SQL code, do not add variable parameters directly into the string. Instead, use the new methods for including parameters.

Correct:

$DB->get_record_sql('SELECT * FROM {course} WHERE id <> ?', array($exceptid));

Wrong:

$DB->get_record_sql('SELECT * FROM {course} WHERE id <> ' . $exceptid);

(Using parameters properly avoids possible serious security holes.)

* When using SQL code, do not use the $CFG->prefix variable. Instead use the new {tablename} syntax.

Correct:

$DB->get_record_sql('SELECT * FROM {course} WHERE id <> ?', array($exceptid));

Wrong:

$DB->get_record_sql("SELECT * FROM {$CFG->prefix}course WHERE id <> ?', array($exceptid));

Development:Module visibility and display

2011-01-10T13:52:22Z

Quen: /* Access permissions */

This document is '''only a proposal'''. The functionality described doesn't exist yet in Moodle.

== DRAFT 2 ==

This is the second draft of the proposal, with changes based on Petr's comments. As well as/because of adding all the class stuff, this version no longer requires rebuild_course_cache and should be 100% backward compatible with all existing uses of modinfo.

Notes:

* Petr wanted dynamic/lazy computation of some of the access stuff - this is necessary for the forum unread data etc, but not feasible to do in this version for any of the data that is already included in modinfo, because of the requirement for 100% BC which is not possible with __get methods; so all the existing property values must be initialised (see below). This also means it's a less scary change, i.e. more moving code around and less new code.

* I wanted a class for the overall thing, which I called course_modinfo (because it's basically from the modinfo field of the course table). Then I neeed a name for the class for an individual module instance info. Petr suggested module_info but I thought cm_info was a bit closer (module_info might sound like it was about a whole module, not one instance). Anyhow, both names subject to change if anyone has better suggestions.

* Linking the cm_info to its parent course_modinfo gives a nice framework to do caching/lazy-initialisation stuff. For instance when we calculate forum unread data in the mod_forum_cm_info_view function, we will get a request for a single $cminfo, but can actually retrieve the data for all forum instances on the course at once (same as at present).

* I didn't specify exactly how to address modinfo caching issues (...if there are any) but because this proposal suggests moving the 'work out the values' stuff into the class, and leaving get_fast_modinfo to deal only with caching, it should be a whole lot simpler to see how the caching works and alter it in future.

== Summary ==

We would like to create a generic API that allows the following:

* Module display on front page can be customised, for example making it possible to create another module that behaves like Label (displaying arbitrary html rather than a link to activity view.php) - currently this is hardcoded hack for Label. This change should apply to other areas such as navigation block as well as course page.

* Some modules can provide dynamic text, such as forum displaying unread messages. At present this is hardcoded so that only forum can do it.

* Modules can be hidden completely, or greyed out, from the view of particular students according to either custom module behaviour, or (if not specified by module) default behaviour regarding a new capability moodle/course:viewactivity and the existing option for whether a non-available module is greyed out or hidden entirely.

This should take advantage of the existing modinfo cache in order that performance is not adversely affected.

== API improvement ==

Following Petr's suggestions, we would also like to improve the API by switching the modinfo in-memory data structures to use defined classes instead of anonymous stdClass objects. This achieves the following:

* Provides a location for documentation of these structures. (Currently they are undocumented.)

* In future, allows functions to specify the required type (i.e. some functions require the information from modinfo, not just a row from the table; they will now be able to specify this). There is no plan to change function definitions immediately.

* Where the type is defined, makes metadata available to IDEs, allowing code completion and automatic documentation viewing.

The following requirements should also be met:

* 100% backward compatibility for existing use of these structures by core and third-party modules. (Obviously, where these want to support the new features, such as the navigation supporting other label-like modules, there do need to be changes which are included in these patch. But if we forget something or it's third-party, it should keep working as at present.)

* 100% backward compatibility for existing modinfo data (in database).

== Removing existing hacks ==

* Existing hacks regarding label in all areas of code (e.g. navigation, etc) will be changed from the logic 'is this a label?' to the logic 'does this activity have a view page?' (which will work for label too)
* Existing hacks regarding forum unread data will be removed and the forum unread code will be moved into the new API function. The code will be written in such a way as to have the same performance characteristics.

== get_fast_modinfo change ==

The get_fast_modinfo function will be changed to return a new object of type course_modinfo, which will be compatible with the existing $modinfo return value.

While constructing this object, in addition to current behaviour, the system will:

* support new values defined in _get_coursemodule_info

* extend dynamic per-user calculation (that checks is something is visible to current user, ->uservisible) with additional checks

* call the new module API (if provided) after calculating modinfo, to get dynamic information

== course_modinfo ==

The new class course_modinfo will contain properties:

* courseid, userid (ints)
* sections (array of int => array of int)
* cms (array of int => cm_info)
* instances (array of string => array of int => cm_info)
* groups - at present I can't tell what this is for as it seems to be empty for me even though there are groups on the course and I'm a member of one of them - hmmm - anyhow I will figure it out and implement it

These are identical to the values currently returned by modinfo, except for the use of cm_info class instead of bare stdClass for the information about modules.

There are three options for handling this class:

# Make these properties public so that they can be accessed exactly as at present.
# Make them private and use PHP magic __set and __get functions so that they can be read as normal but any attempt to write them would (while working) also cause a developer debug warning.
# Make the properties public, but deprecate them, and create separate get methods (get_courseid, get_userid, etc) which are recommended for future use.

I initially favoured the second option but unfortunately, PHP being PHP, this doesn't quite work properly: specifically, you can't use the empty() function on such values. Since there might be places in the code that call empty(), maybe this isn't a good idea.

Consequently I tend to the third one; we should make better get methods such as get_cm($cmid) as well as just get_cms(), which may help make new code more readable.

=== Construction ===

The code that creates this information should largely be moved to this class (either in a constructor or in init methods etc) from its current location in get_fast_modinfo. get_fast_modinfo should remain responsible only for caching these objects.

== cm_info class ==

=== Basic structure ===

The new class cm_info will be constructed with a $parent (course_modinfo). Knowing its parent allows the class to carry out operations with regard to the whole course, where this is beneficial for performance, without needing extra parameters. There will be a get_modinfo() method to return this.

=== Defined states ===

This class has three states:

* BASIC_DATA: class has the data from database modinfo table, and automatically completed data that is not related to the current user.
* DYNAMIC_DATA: class has all data that is available for most pages, including data related to the current request from the current user's permissions and the _cm_info_dynamic function if applicable.
* VIEW_DATA: class also has the data that is needed only on the course view page (or similar pages) from the _cm_info_view function if applicable (basically only used for forum unread data and stuff like that).

When get_fast_modinfo returns, all returned objects will be in DYNAMIC_DATA state. This will be sufficient for determining whether the current user has access to the activity and for displaying the basic link etc. Basically the only thing it doesn't include is supplemental data that is only needed on the course page, such as forum unread data (get_after_link function). This data takes time to calculate so is generated on request.

The intention is that getting to DYNAMIC_DATA state shouldn't require any database calls (certainly for the core modules). Getting to VIEW_DATA state may require database calls, e.g. to calculate the number of unread forum posts.

=== Existing properties ===

These properties are in current modinfo:

* id, instance, course, idnumber, visible, groupmode, groupingid, groupmembersonly, indent, completion, availablefrom, availableuntil, showavailability - data from course_modules row

* extra, icon, iconcomponent, modname, name, sectionnum, conditionscompletion, conditionsgrade, modplural (wtf is this there when the singular name isn't and both should be available with get_string?!) - data from modinfo which was computed when generating the cache

* availableinfo, available, uservisible - data relating to the current user which is computed dynamically when obtaining the modinfo object

This is the list of properties currently available in modinfo objects, so will be implemented as-is. The same question regarding use of __set, __get applies as above, but in this case it's perhaps more likely that people might call empty() on the existing properties; again, I propose retaining the above as public properties, but deprecated, and providing get_x methods for new use. Any new properties would be private and available only with get_ methods.

Some of the get methods might have a slightly different definition to the raw properties. For example get_icon should use the provided data to return a moodle_icon object (if there is one? I am not sure), not a string.

=== New data / get methods ===

The new data and corresponding get methods are:

* has_view() - true if the module should have a link to its view.php shown in navigation, be included in lists of 'did the user visit this module' stats, etc. (Basically this is the 'is not a label' method.)
* get_url() - returns moodle_url to module view.php, or null if has_view is false (this reduces code duplication in various places)
* get_content() # - returns HTML content to be displayed on the course page where this module is placed; appears below the link, if present (this is how Label displays content on course page)
* get_extra_classes() # - returns additional CSS classes to be added to the A or DIV tag(s) for this item on main course page.
* get_custom_data() - returns an optional mixed value containing custom data for this module, which needs to be available course-wide via the get_fast_modinfo function.
* get_after_link() # - returns HTML code which displays after the link.
* get_after_edit_icons() # - returns HTML code which displays after the standard icons (hide, edit, delete, etc) when editing.

Functions marked # require 'view information'. This is additional information intended for use on the course view page and not in other places that use modinfo: the most obvious example (and the only one that affects core) is forum unread data. Consequently it is only obtained on request (see state information above). Obtaining view info requires calling the module's _cm_info_view function if it has one.

=== Set methods ===

Set methods are available for use only by _cm_info_dynamic and _cm_info_view functions; see below.

== Modify _get_coursemodule_info ==

There will be a change to the existing module API function _get_coursemodule_info which is used to update information before storing it in the database modinfo field. This change will retain backward compatibility.

The function returns an object which is currently a stdClass object. This possibility will be retained for backward compatibility, with unchanged behaviour. All existing fields are supported:

* name: name of instance or (for labels only) content of instance
* icon: name of icon or special weird string
* iconcomponent: component of icon, possibly works
* extra: extra data inserted somewhere horrible in the html

These fields are all optional and may be left unset to accept the defaults.

However a new class cached_cm_info can be returned instead.

The class cached_cm_info has the following properties:

* name, icon, iconcomponent: as before
* content: HTML content to be displayed on the course page where this module is placed; appears below the link, if present (this is how a Label-like module can display content on course page)
* customdata: A place to store a string or object containing custom data for this module, which needs to be available course-wide via the get_fast_modinfo function. If present, this data should be small in size.
* extraclasses: Extra CSS classes to add to the item on course page display, if required.

(It does not support extra, which is deprecated on account of being stupid, at least unless I figure out some existing use case that really needs to be carried forward into a non-deprecated system.)

=== Storing data ===

Returning a stdClass object should result in identical content of the modinfo field in the database to present.

Return cached_cm_info results in similar content but with extra fields ->content and ->customdata. These fields are only stored if they are non-null, i.e. it won't bulk up the database with empty 'content=nothing' type data against every module.

=== Reading label data ===

The new content field is different to existing behaviour of the Label module, which stores its content in the 'name' field as noted. When reading this data or processing it (for example in cm_info class), the system takes the following approach:

* if the modname is 'label' and there is no 'content' field, then copy the 'name' field into 'content'.

Note that this behaviour retains backward compatibility; the label still has a silly 'name' value. For new code, has_view() returns false so it won't use name; for old code, the existing hard-coded exceptions for label will continue to work.

== Extend dynamic calculation ==

Currently the modinfo code makes the following checks that apply dynamically per-request (and do not directly come from the cache) in order to create the ->uservisible member variable.

* If ->groupmembersonly is set, checks if the user belongs to group or has accessallgroups.
* If availability restrictions (date, grade, completion) are set, checks these (also even if available to current user, stores information into ->availableinfo, ->available for information when editing).

My proposal is:

* Make this part of the code (that 'specialises' a single mod value for the current user/request) into a separate function within cm_info class, just to simplify it. This function should be the one that changes the cm_info state from BASIC_DATA to DYNAMIC_DATA.
* Add a check for the moodle/course:viewactivity capability; if user doesn't have this capability, set ->uservisible to false. Also check the option about what to do with hidden activities; if this is set to the default 'grey it out', then set ->inactive to true.
** Note: The default value for moodle/course:viewactivity should be true for all roles, even guest. This maintains existing behaviour. Sites that don't want guests to view activities can change the main role definition for guest.
* Call the _cm_info_dynamic function (below) if the current module supplies one.

PERFORMANCE CONCERNS: Minimal. No new database queries are required, just a capability check and a function existence check.

== New module API ==

Two new module API functions will be defined. They both have one parameter: the cm_info object for this module, containing all the data from the modinfo cache.

The functions are:

* _cm_info_dynamic - add basic data that is always required (must be fast; should not make any database calls)
* _cm_info_view - add data that is required for the course view page (may make database calls)

The functions both call set methods in the cm_info object. Examples:

* set_user_visible(false) - hide activity entirely
* set_available(false) - grey out activity while it remains visible
* set_available_info('not available because you suck') - add explanation for why it's not available
* '''set_after_link'''('16 unread') # - add html code to appear after link
* '''set_edit_icons'''($html) # - add some code to appear when editing
* set_has_view(false) - make module not have link, navigation, etc even if it has a view.php
* set_content($html) # - add/change code to appear below the link
* set_name($text) - change text of the link
* set_extra_classes('whatever classes') # - add CSS classes

The bold functions set cm_info data that cannot be set anywhere else (such as by system defaults or modinfo classes). This is basically because there didn't seem any general need to cache this data, particularly bearing in mind that modules can cache anything they like using the customdata property of cached_cm_info.

_cm_info_view is restricted: for example, you cannot change user_visible status in view (because then it wouldn't work when checking access etc on other pages). You can only change the 'view' properties. This can be enforced by making the set methods throw exceptions if called when the cm_info is in its already-defined state.

Should it be necessary, this function can access the existing information in the cm_info object and also in the parent course_modinfo object (such as the user id) by calling get_modinfo on the cm_info.

PERFORMANCE CONCERNS: None. Of standard modules, only the forum will implement this and only in the 'view' version used just on course page; it will use the same code as at present. Custom modules will need to be written carefully in a similar manner so that they also perform well (ie do any queries once for whole course and store in global cache, not once per module).

== Access permissions ==

When calling require_login with a $cm parameter, this will do get_fast_modinfo and check the is_user_visible() method in order to process per-user access restrictions:

* groupmembersonly
* moodle/course:viewactivity

PERFORMANCE CONCERNS: Because require_login like this is used on all module pages, we should use a profiler to evaluate before/after performance of this change and ensure that it isn't worsened. I suspect it won't be, because I think it already checks groupmembersonly anyway, so it's doing basically the same test; and I think most pages already call get_fast_modinfo e.g. for navigation block.

NOTE: The way modules currently initialise is a bit inefficient, if get_fast_modinfo is to be used. The current sequence on most module pages is something like:

* get course module (from id, supplied)
* get course
* get instance

(3 queries)

we could change this to

* get course (from simple join using cmid, supplied)
* use get_fast_modinfo to get cm
* get instance

(2 queries)

Not suggesting that as part of this change (and it probably shouldn't be in this document), just saying...

Development:Module visibility and display

2011-01-10T13:43:08Z

Quen: /* Existing properties */

This document is '''only a proposal'''. The functionality described doesn't exist yet in Moodle.

== DRAFT 2 ==

This is the second draft of the proposal, with changes based on Petr's comments. As well as/because of adding all the class stuff, this version no longer requires rebuild_course_cache and should be 100% backward compatible with all existing uses of modinfo.

Notes:

* Petr wanted dynamic/lazy computation of some of the access stuff - this is necessary for the forum unread data etc, but not feasible to do in this version for any of the data that is already included in modinfo, because of the requirement for 100% BC which is not possible with __get methods; so all the existing property values must be initialised (see below). This also means it's a less scary change, i.e. more moving code around and less new code.

* I wanted a class for the overall thing, which I called course_modinfo (because it's basically from the modinfo field of the course table). Then I neeed a name for the class for an individual module instance info. Petr suggested module_info but I thought cm_info was a bit closer (module_info might sound like it was about a whole module, not one instance). Anyhow, both names subject to change if anyone has better suggestions.

* Linking the cm_info to its parent course_modinfo gives a nice framework to do caching/lazy-initialisation stuff. For instance when we calculate forum unread data in the mod_forum_cm_info_view function, we will get a request for a single $cminfo, but can actually retrieve the data for all forum instances on the course at once (same as at present).

* I didn't specify exactly how to address modinfo caching issues (...if there are any) but because this proposal suggests moving the 'work out the values' stuff into the class, and leaving get_fast_modinfo to deal only with caching, it should be a whole lot simpler to see how the caching works and alter it in future.

== Summary ==

We would like to create a generic API that allows the following:

* Module display on front page can be customised, for example making it possible to create another module that behaves like Label (displaying arbitrary html rather than a link to activity view.php) - currently this is hardcoded hack for Label. This change should apply to other areas such as navigation block as well as course page.

* Some modules can provide dynamic text, such as forum displaying unread messages. At present this is hardcoded so that only forum can do it.

* Modules can be hidden completely, or greyed out, from the view of particular students according to either custom module behaviour, or (if not specified by module) default behaviour regarding a new capability moodle/course:viewactivity and the existing option for whether a non-available module is greyed out or hidden entirely.

This should take advantage of the existing modinfo cache in order that performance is not adversely affected.

== API improvement ==

Following Petr's suggestions, we would also like to improve the API by switching the modinfo in-memory data structures to use defined classes instead of anonymous stdClass objects. This achieves the following:

* Provides a location for documentation of these structures. (Currently they are undocumented.)

* In future, allows functions to specify the required type (i.e. some functions require the information from modinfo, not just a row from the table; they will now be able to specify this). There is no plan to change function definitions immediately.

* Where the type is defined, makes metadata available to IDEs, allowing code completion and automatic documentation viewing.

The following requirements should also be met:

* 100% backward compatibility for existing use of these structures by core and third-party modules. (Obviously, where these want to support the new features, such as the navigation supporting other label-like modules, there do need to be changes which are included in these patch. But if we forget something or it's third-party, it should keep working as at present.)

* 100% backward compatibility for existing modinfo data (in database).

== Removing existing hacks ==

* Existing hacks regarding label in all areas of code (e.g. navigation, etc) will be changed from the logic 'is this a label?' to the logic 'does this activity have a view page?' (which will work for label too)
* Existing hacks regarding forum unread data will be removed and the forum unread code will be moved into the new API function. The code will be written in such a way as to have the same performance characteristics.

== get_fast_modinfo change ==

The get_fast_modinfo function will be changed to return a new object of type course_modinfo, which will be compatible with the existing $modinfo return value.

While constructing this object, in addition to current behaviour, the system will:

* support new values defined in _get_coursemodule_info

* extend dynamic per-user calculation (that checks is something is visible to current user, ->uservisible) with additional checks

* call the new module API (if provided) after calculating modinfo, to get dynamic information

== course_modinfo ==

The new class course_modinfo will contain properties:

* courseid, userid (ints)
* sections (array of int => array of int)
* cms (array of int => cm_info)
* instances (array of string => array of int => cm_info)
* groups - at present I can't tell what this is for as it seems to be empty for me even though there are groups on the course and I'm a member of one of them - hmmm - anyhow I will figure it out and implement it

These are identical to the values currently returned by modinfo, except for the use of cm_info class instead of bare stdClass for the information about modules.

There are three options for handling this class:

# Make these properties public so that they can be accessed exactly as at present.
# Make them private and use PHP magic __set and __get functions so that they can be read as normal but any attempt to write them would (while working) also cause a developer debug warning.
# Make the properties public, but deprecate them, and create separate get methods (get_courseid, get_userid, etc) which are recommended for future use.

I initially favoured the second option but unfortunately, PHP being PHP, this doesn't quite work properly: specifically, you can't use the empty() function on such values. Since there might be places in the code that call empty(), maybe this isn't a good idea.

Consequently I tend to the third one; we should make better get methods such as get_cm($cmid) as well as just get_cms(), which may help make new code more readable.

=== Construction ===

The code that creates this information should largely be moved to this class (either in a constructor or in init methods etc) from its current location in get_fast_modinfo. get_fast_modinfo should remain responsible only for caching these objects.

== cm_info class ==

=== Basic structure ===

The new class cm_info will be constructed with a $parent (course_modinfo). Knowing its parent allows the class to carry out operations with regard to the whole course, where this is beneficial for performance, without needing extra parameters. There will be a get_modinfo() method to return this.

=== Defined states ===

This class has three states:

* BASIC_DATA: class has the data from database modinfo table, and automatically completed data that is not related to the current user.
* DYNAMIC_DATA: class has all data that is available for most pages, including data related to the current request from the current user's permissions and the _cm_info_dynamic function if applicable.
* VIEW_DATA: class also has the data that is needed only on the course view page (or similar pages) from the _cm_info_view function if applicable (basically only used for forum unread data and stuff like that).

When get_fast_modinfo returns, all returned objects will be in DYNAMIC_DATA state. This will be sufficient for determining whether the current user has access to the activity and for displaying the basic link etc. Basically the only thing it doesn't include is supplemental data that is only needed on the course page, such as forum unread data (get_after_link function). This data takes time to calculate so is generated on request.

The intention is that getting to DYNAMIC_DATA state shouldn't require any database calls (certainly for the core modules). Getting to VIEW_DATA state may require database calls, e.g. to calculate the number of unread forum posts.

=== Existing properties ===

These properties are in current modinfo:

* id, instance, course, idnumber, visible, groupmode, groupingid, groupmembersonly, indent, completion, availablefrom, availableuntil, showavailability - data from course_modules row

* extra, icon, iconcomponent, modname, name, sectionnum, conditionscompletion, conditionsgrade, modplural (wtf is this there when the singular name isn't and both should be available with get_string?!) - data from modinfo which was computed when generating the cache

* availableinfo, available, uservisible - data relating to the current user which is computed dynamically when obtaining the modinfo object

This is the list of properties currently available in modinfo objects, so will be implemented as-is. The same question regarding use of __set, __get applies as above, but in this case it's perhaps more likely that people might call empty() on the existing properties; again, I propose retaining the above as public properties, but deprecated, and providing get_x methods for new use. Any new properties would be private and available only with get_ methods.

Some of the get methods might have a slightly different definition to the raw properties. For example get_icon should use the provided data to return a moodle_icon object (if there is one? I am not sure), not a string.

=== New data / get methods ===

The new data and corresponding get methods are:

* has_view() - true if the module should have a link to its view.php shown in navigation, be included in lists of 'did the user visit this module' stats, etc. (Basically this is the 'is not a label' method.)
* get_url() - returns moodle_url to module view.php, or null if has_view is false (this reduces code duplication in various places)
* get_content() # - returns HTML content to be displayed on the course page where this module is placed; appears below the link, if present (this is how Label displays content on course page)
* get_extra_classes() # - returns additional CSS classes to be added to the A or DIV tag(s) for this item on main course page.
* get_custom_data() - returns an optional mixed value containing custom data for this module, which needs to be available course-wide via the get_fast_modinfo function.
* get_after_link() # - returns HTML code which displays after the link.
* get_after_edit_icons() # - returns HTML code which displays after the standard icons (hide, edit, delete, etc) when editing.

Functions marked # require 'view information'. This is additional information intended for use on the course view page and not in other places that use modinfo: the most obvious example (and the only one that affects core) is forum unread data. Consequently it is only obtained on request (see state information above). Obtaining view info requires calling the module's _cm_info_view function if it has one.

=== Set methods ===

Set methods are available for use only by _cm_info_dynamic and _cm_info_view functions; see below.

== Modify _get_coursemodule_info ==

There will be a change to the existing module API function _get_coursemodule_info which is used to update information before storing it in the database modinfo field. This change will retain backward compatibility.

The function returns an object which is currently a stdClass object. This possibility will be retained for backward compatibility, with unchanged behaviour. All existing fields are supported:

* name: name of instance or (for labels only) content of instance
* icon: name of icon or special weird string
* iconcomponent: component of icon, possibly works
* extra: extra data inserted somewhere horrible in the html

These fields are all optional and may be left unset to accept the defaults.

However a new class cached_cm_info can be returned instead.

The class cached_cm_info has the following properties:

* name, icon, iconcomponent: as before
* content: HTML content to be displayed on the course page where this module is placed; appears below the link, if present (this is how a Label-like module can display content on course page)
* customdata: A place to store a string or object containing custom data for this module, which needs to be available course-wide via the get_fast_modinfo function. If present, this data should be small in size.
* extraclasses: Extra CSS classes to add to the item on course page display, if required.

(It does not support extra, which is deprecated on account of being stupid, at least unless I figure out some existing use case that really needs to be carried forward into a non-deprecated system.)

=== Storing data ===

Returning a stdClass object should result in identical content of the modinfo field in the database to present.

Return cached_cm_info results in similar content but with extra fields ->content and ->customdata. These fields are only stored if they are non-null, i.e. it won't bulk up the database with empty 'content=nothing' type data against every module.

=== Reading label data ===

The new content field is different to existing behaviour of the Label module, which stores its content in the 'name' field as noted. When reading this data or processing it (for example in cm_info class), the system takes the following approach:

* if the modname is 'label' and there is no 'content' field, then copy the 'name' field into 'content'.

Note that this behaviour retains backward compatibility; the label still has a silly 'name' value. For new code, has_view() returns false so it won't use name; for old code, the existing hard-coded exceptions for label will continue to work.

== Extend dynamic calculation ==

Currently the modinfo code makes the following checks that apply dynamically per-request (and do not directly come from the cache) in order to create the ->uservisible member variable.

* If ->groupmembersonly is set, checks if the user belongs to group or has accessallgroups.
* If availability restrictions (date, grade, completion) are set, checks these (also even if available to current user, stores information into ->availableinfo, ->available for information when editing).

My proposal is:

* Make this part of the code (that 'specialises' a single mod value for the current user/request) into a separate function within cm_info class, just to simplify it. This function should be the one that changes the cm_info state from BASIC_DATA to DYNAMIC_DATA.
* Add a check for the moodle/course:viewactivity capability; if user doesn't have this capability, set ->uservisible to false. Also check the option about what to do with hidden activities; if this is set to the default 'grey it out', then set ->inactive to true.
** Note: The default value for moodle/course:viewactivity should be true for all roles, even guest. This maintains existing behaviour. Sites that don't want guests to view activities can change the main role definition for guest.
* Call the _cm_info_dynamic function (below) if the current module supplies one.

PERFORMANCE CONCERNS: Minimal. No new database queries are required, just a capability check and a function existence check.

== New module API ==

Two new module API functions will be defined. They both have one parameter: the cm_info object for this module, containing all the data from the modinfo cache.

The functions are:

* _cm_info_dynamic - add basic data that is always required (must be fast; should not make any database calls)
* _cm_info_view - add data that is required for the course view page (may make database calls)

The functions both call set methods in the cm_info object. Examples:

* set_user_visible(false) - hide activity entirely
* set_available(false) - grey out activity while it remains visible
* set_available_info('not available because you suck') - add explanation for why it's not available
* '''set_after_link'''('16 unread') # - add html code to appear after link
* '''set_edit_icons'''($html) # - add some code to appear when editing
* set_has_view(false) - make module not have link, navigation, etc even if it has a view.php
* set_content($html) # - add/change code to appear below the link
* set_name($text) - change text of the link
* set_extra_classes('whatever classes') # - add CSS classes

The bold functions set cm_info data that cannot be set anywhere else (such as by system defaults or modinfo classes). This is basically because there didn't seem any general need to cache this data, particularly bearing in mind that modules can cache anything they like using the customdata property of cached_cm_info.

_cm_info_view is restricted: for example, you cannot change user_visible status in view (because then it wouldn't work when checking access etc on other pages). You can only change the 'view' properties. This can be enforced by making the set methods throw exceptions if called when the cm_info is in its already-defined state.

Should it be necessary, this function can access the existing information in the cm_info object and also in the parent course_modinfo object (such as the user id) by calling get_modinfo on the cm_info.

PERFORMANCE CONCERNS: None. Of standard modules, only the forum will implement this and only in the 'view' version used just on course page; it will use the same code as at present. Custom modules will need to be written carefully in a similar manner so that they also perform well (ie do any queries once for whole course and store in global cache, not once per module).

== Access permissions ==

When calling require_login with a $cm parameter, this will do get_fast_modinfo and check the is_user_visible() method in order to process per-user access restrictions:

* groupmembersonly
* moodle/course:viewactivity

PERFORMANCE CONCERNS: Because require_login like this is used on all module pages, we should use a profiler to evaluate before/after performance of this change and ensure that it isn't worsened. I suspect it won't be, see below.

NOTE: The way modules currently initialise is a bit inefficient, especially if get_fast_modinfo is to be used (and I suspect it already is on most pages, given the navigation block probably uses it). The current sequence on most module pages is something like:

* get course module (from id, supplied)
* get course
* get instance

(3 queries)

we could change this to

* get course (from simple join using cmid, supplied)
* use get_fast_modinfo to get cm
* get instance

(2 queries)

Not suggesting that as part of this change (and it probably shouldn't be in this document), just saying...