MoodleDocs - User contributions [en]

Performance recommendations

2011-08-08T12:59:39Z

Marxjohnson: Removed warning about unsupported versions of IE and SSL Keepalive

{{Server settings}}
<p class="note">'''Please refer to [[Page_notes#Server settings|these notes]] before editing this page.'''</p>

Location: ''Administration > Server > Performance''

Moodle can be made to perform very well, at small usage levels or scaling up to many thousands of users. The factors involved in performance are basically the same as for any PHP-based database-driven system. When trying to optimize your server, try to focus on the factor which will make the most difference to the user. For example, if you have relatively more users browsing than accessing the database, look to improve the webserver performance.

==Obtain a baseline benchmark==

Before attempting any optimization, you should obtain a baseline benchmark of the component of the system you are trying to improve. For Linux try [http://lbs.sourceforge.net/ LBS] and for Windows use the Performance Monitor. Once you have quantitative data about how your system is performing currently, you'll be able to determine if the change you have made has had any real impact.

The overall aim of adjustments to improve performance is to use RAM (cacheing) and to reduce disk-based activity. It is especially important to try to eliminate swap file usage as much as you can. If your system starts swapping, this is a sign that you need more RAM.

The '''optimization order preference''' is usually: primary storage (more RAM), secondary storage (faster hard disks/improved hard disk configuration), processor (more and faster).

==Scalability==

Moodle's design (with clear separation of application layers) allows for strongly scalable setups. (Please check the list of [[Large installations|large Moodle installations]].)

Large sites usually separate the web server and database onto separate servers, although for smaller installations this is typically not necessary.

It is possible to load-balance a Moodle installation, for example by using more than one webserver. The separate webservers should query the same database and refer to the same filestore area, but otherwise the separation of the application layers is complete enough to make this kind of clustering feasible. Similarly, the database could be a cluster of servers (e.g. a MySQL cluster), but this is not an easy task and you should seek expert support, e.g. from a Moodle Partner.

'''See also''':
*[[Server cluster]]
*[http://moodle.org/mod/forum/discuss.php?d=4801 Scalability] forum discussion.
*[http://moodle.org/mod/forum/discuss.php?d=57202 Moodle clustering] forum discussion.
*[http://moodle.org/mod/forum/discuss.php?d=44470 Software load balancing] forum discussion.
*[http://moodle.org/mod/forum/discuss.php?d=49986 TCP load balancing] forum dicsussion.

==Hardware configuration==
'''Note''': The fastest and most effective change that you can make to improve performance is to '''increase the amount of RAM on your web server''' - get as much as possible (eg 4GB). Increasing primary memory will reduce the need for processes to swap to disk and will enable your server to handle more users.
* Better performance is gained by obtaining the best '''processor capability''' you can, i.e. dual or dual core processors. A modern BIOS should allow you to enable hyperthreading, but check if this makes a difference to the overall performance of the processors by using a [http://en.wikipedia.org/wiki/Super_PI CPU benchmarking tool].
* If you can afford them, use '''SCSI hard disks''' instead of SATA drives. SATA drives will increase your system's CPU utilization, whereas SCSI drives have their own integrated processors and come into their own when you have multiple drives. If you must have SATA drives, check that your motherboard and the drives themselves support NCQ (Native Command Queuing).
* Purchase hard disks with a '''low seek time'''. This will improve the overall speed of your system, especially when accessing Moodle's reports.
* Size your '''swap file''' correctly. The general advice is to set it to 4 x physical RAM.
* Use a '''RAID disk system'''. Although there are many different RAID configurations you can create, the following generally works best:
** install a hardware RAID controller (if you can)
** the operating system and swap drive on one set of disks configured as RAID-1.
** Moodle, Web server and Database server on another set of disks configured as RAID-5.
* Use '''gigabit ethernet''' for improved latency and throughput. This is especially important when you have your webserver and database server separated out on different hosts.
* Check the settings on your '''network card'''. You may get an improvement in performance by increasing the use of buffers and transmit/receive descriptors (balance this with processor and memory overheads) and off-loading TCP checksum calculation onto the card instead of the OS.
* Read this [http://moodle.org/mod/forum/discuss.php?d=68579 Case Study] on a server stress test with 300 users.
* See this [http://elearning.sgu.ac.jp/doc/PT/ accompanying report] on network traffic and server loads.
* See the [[Moodle.org configuration]]
* Also see this SFSU presentation at Educause (using VMWare): [http://www.educause.edu/Resources/AnOpenSourceLMSforaMissionCrit/162843]

==Operating System==
* You can use [http://en.wikipedia.org/wiki/Linux Linux](recommended), Unix-based, Windows or Mac OS X for the server '''operating system'''. *nix operating systems generally require less memory than Mac OS X or Windows servers for doing the same task as the server is configured with just a shell interface. Additionally Linux does not have licensing fees attached, but can have a big learning curve if you're used to another operating system. If you have a large number of processors running SMP, you may also want to consider using a highly tuned OS such as [http://en.wikipedia.org/wiki/Solaris_Operating_Environment Solaris].
* Check your own OS and '''vendor specific instructions''' for optimization steps.
** For Linux look at the [http://linuxperf.sourceforge.net/ Linux Performance Team] site.
** For Linux investigate the hdparm command, e.g. hdparm -m16 -d1 can be used to enable read/write on multiple sectors and DMA. Mount disks with the async and noatime options.
** For Windows set the sever to be optimized for network applications (Control Panel, Network Connections, LAN connection, Properties, File & Printer Sharing for Microsoft Networks, Properties, Optimization). You can also search the [http://technet.microsoft.com/ Microsoft TechNet site] for optimization documents.

==Web server performance==

Installing [http://www.mozilla.com/en-US/ Firefox] and the [https://addons.mozilla.org/en-US/firefox/addon/1843 firebug] extension will allow you to watch the time it takes for each page component to load. Also, the [https://addons.mozilla.org/en-US/firefox/addon/5369 Yslow] extension will evaluate your page against Yahoo's [http://www.skrenta.com/2007/05/14_rules_for_fast_web_pages_by_1.html 14 rules], full text [http://developer.yahoo.com/performance/rules.html Best Practices for Speeding Up Your Web Site], <strike>([http://video.yahoo.com/video/play?vid=1040890 video])</strike> for fast loading websites.

===PHP performance===
* You are strongly recommended to use a '''PHP accelerator''' to ease CPU load, such as [http://pecl.php.net/apc APC], [http://www.php-accelerator.co.uk/ PHPA], [http://trac.lighttpd.net/xcache/ Xcache] or [http://eaccelerator.net/ eAccelerator]. (Take care to choose a PHP accelerator that is known to work well with your version of PHP and note that Turck MMCache is [http://turckmmcache.exeprod.com/TheManifestoEnglish no longer maintained] and can cause failures with PHP 5).
* Improvements in read/write performance can be improved by putting the cached PHP pages on a [[TMPFS]] filesystem - but remember that you'll lose the cache contents when there is a power failure or the server is rebooted.
* Performance of PHP is better when installed as an '''Apache/IIS ISAPI module''' (rather than a CGI).
* Also check the '''memory_limit''' in php.ini, reduce it to 16M for Moodle version earlier than 1.7 ([http://moodle.org/mod/forum/discuss.php?d=39656 See this forum discussion]). For Moodle 1.7 or later, it is recommended that the value of memory_limit should be 40M. As of [http://www.php.net/ChangeLog-5.php PHP 5.2.1] the default value for the memory_limit directive is 128M.
* Also see [[PHP_settings_by_Moodle_version]]

===Install HowTo===
* [http://2bits.com/articles/installing-php-apc-gnulinux-centos-5.html APC on CentOS 5.x (linux)]
* [http://fplanque.com/dev/linux/install-apc-php-cache-debian-lenny APC on Debian (linux)]
* [http://www.linuxtuts.net/211-installing-memcached-php5-memcache-module-debian-apache2.html MemCache module on Debian (Apache2 and PHP5) ]
* [http://noveckg.blogspot.com/2010/03/installing-memcached-on-centos-5x.html Installing Memcache on CentOS 5.x (linux)]
* [http://noveckg.blogspot.com/2010/02/installing-eaccelerator-cache-for-php.html Installing eAccelerator on CentOS 5.x (linux)]
* [https://docs.moodle.org/en/Installing_eAccelerator_In_Ubuntu_Server/ Installing eAccelerator on Ubuntu Server (linux)]

===Apache performance===
* If you are using Apache on a Windows server, use the build from [http://www.apachelounge.com Apache Lounge] which is reported to have [http://moodle.org/mod/forum/discuss.php?d=93358 performance and stability improvements] compared to the official Apache download. Note that this is an unofficial build, so may not keep up with official releases.
* Set the '''MaxClients''' directive correctly. Use this formula to help (which uses 80% of available memory to leave room for spare):
MaxClients = Total available memory * 80% / Max memory usage of apache process
:Memory usage of apache process is usually 10MB, so a general rule of thumb is to divide your available memory in megabytes by 10 to get the value of MaxClients. To find the max memory usage of apache processes read the value from the shell command:
#ps -ylC httpd --sort:rss

:If you need to increase the value of '''MaxClients''' beyond 256, you will also need to set the '''ServerLimit''' directive.

:'''Warning''': Do not be tempted to set the value of MaxClients higher than your available memory as your server will consume more RAM than available and start to swap to disk.
* Consider reducing the '''number of modules''' that Apache loads in the httpd.conf file to the minumum necessary to reduce the memory needed.
* Use the '''latest version of Apache''' - Apache 2 has an improved memory model which reduces memory usage further.
* For Unix/Linux systems, consider lowering '''MaxRequestsPerChild''' in httpd.conf to as low as 20-30 (if you set it any lower the overhead of forking begins to outweigh the benefits).
* For a heavily loaded server, consider setting '''KeepAlive Off''' (do this only if your Moodle pages do not contain links to resources or uploaded images) or lowering the '''KeepAliveTimeout''' to between 2 and 5. The default is 15 (seconds) - the higher the value the more server processes will be kept waiting for possibly idle connections. A more accurate value for KeepAliveTimeout is obtained by observing how long it takes your users to download a page. After altering any of the KeepAlive variables, monitor your CPU utilization as there may be an additional overhead in initiating more worker processes/threads.
* As an alternative to using KeepAlive Off, consider setting-up a '''Reverse Proxy server''' infront of the Moodle server to cache HTML files with images. You can then return Apache to using keep-alives on the Moodle server.
* If you do not use a .htaccess file, set the '''AllowOverride''' variable to AllowOverride None to prevent .htaccess lookups.
* Set '''DirectoryIndex''' correctly so as to avoid content-negotiation. Here's an example from a production server:
DirectoryIndex index.php index.html index.htm
* Unless you are doing development work on the server, set '''ExtendedStatus Off''' and disable mod_info as well as mod_status.
* Leave '''HostnameLookups Off''' (as default) to reduce DNS latency.
* Consider reducing the value of '''TimeOut''' to between 30 to 60 (seconds).
* For the '''Options directive''', avoid Options Multiviews as this performs a directory scan. To reduce disk I/O further use
Options -Indexes FollowSymLinks
*'''Caching (unsupported)''' - ''Please note that this kind of caching may create major problems during upgrades.'' Apache can be told to make pages load a lot faster by specifying that the browser should cache some various page elements such as images and reuse them from local memory rather than ask for them again every time a page is requested. How to do this varies slightly between OSes but there are two basic steps:

# Install and enable mod_expires - refer to documentation or man pages
# Add this code to the virtual server config file within the <directory> section for the root directory (or within the .htaccess file if AllowOverrides is On):
<IfModule mod_expires.c>
ExpiresActive On
ExpiresDefault "access plus 1 seconds"
ExpiresByType text/html "access plus 1 seconds"
ExpiresByType image/gif "access plus 1 week"
ExpiresByType image/jpeg "access plus 1 week"
ExpiresByType image/png "access plus 1 week"
ExpiresByType text/css "access plus 1 week"
ExpiresByType text/javascript "access plus 1 week"
ExpiresByType application/x-javascript "access plus 1 week"
ExpiresByType text/xml "access plus 1 seconds"
</IfModule>

The effect is to make everything stay in the cache except HTML and XML, which change dynamically. It's possible to gain a several hundred percent decrease in load times this way. Adjust the cache times according to how often your images etc change.

* Compression reduces response times by reducing the size of the HTTP response
# Install and enable mod_deflate - refer to documentation or man pages
# Add this code to the virtual server config file within the <directory> section for the root directory (or within the .htaccess file if AllowOverrides is On):
<ifModule mod_deflate.c>
AddOutputFilterByType DEFLATE text/html text/plain text/xml
</ifmodule>

More info: [http://www.metaskills.net/blog/heuristics/sysadmin/how-to-control-browser-caching-with-apache-2 www.metaskills.net]

===IIS performance===
All alter this location in the registry:
HKLM\SYSTEM\CurrentControlSet\Services\Inetinfo\Parameters\
* The equivalent to KeepAliveTimeout is '''ListenBackLog''' (IIS - registry location is HKLM\ SYSTEM\ CurrentControlSet\ Services\ Inetinfo\ Parameters). Set this to between 2 to 5.
*Change the '''MemCacheSize''' value to adjust the amount of memory (Mb) that IIS will use for its file cache (50% of available memory by default).
*Change the '''MaxCachedFileSize''' to adjust the maximum size of a file cached in the file cache in bytes. Default is 262,144 (256K).
*Create a new DWORD called '''ObjectCacheTTL''' to change the length of time (in milliseconds) that objects in the cache are held in memory. Default is 30,000 milliseconds (30 seconds).

===Lighttpd, NginX and Cherokee performance===
You can increase server performance by using a '''light-weight''' webserver like [http://www.lighttpd.net/ lighttpd], [http://nginx.net/ nginx] or [http://www.cherokee-project.com/ cherokee] in combination with PHP in FastCGI-mode. Lighttpd was originally created as a proof-of-concept[http://www.lighttpd.net/story] to address the [http://www.kegel.com/c10k.html C10k problem] and while primarily recommended for memory-limited servers, its design origins and asynchronous-IO model make it a suitable and proven[http://blog.lighttpd.net/articles/2006/12/28/lighttpd-powers-5-alexa-top-250-sites] alternative HTTP server for high-load websites and web apps, including Moodle. See the [[lighttpd | MoodleDocs Lighttpd page]] for additional information, configuration example and links.

Alternatively, both [http://www.lighttpd.net/ lighttpd] and [http://nginx.net/ nginx] are capable of performing as a load-balancer and/or reverse-proxy to alleviate load on back-end servers[http://www.linuxjournal.com/article/10108], providing benefit without requiring an actual software change on existing servers.

Do note that these are likely to be the least tested server environments of all particularly if you are using advanced features such as web services and/or Moodle Networking. They are probably best considered for heavily used Moodle sites with relatively simple configurations.

==Database performance==

Moodle contains a script which will display some key database performance statistics from the [http://phplens.com/lens/adodb/docs-perf.htm ADOdb performance monitor]. Run the script in your browser as in the following example:

http://www.mymoodle.com/admin/dbperformance.php

Use the data displayed as a guide to tune and improve the performance of your database server.

===MySQL performance===

The following are MySQL specific settings which can be adjusted for better performance in your my.cnf (my.ini in Windows). The file contains a list of settings and their values. To see the current values use these commands
SHOW STATUS;
SHOW VARIABLES;
'''Important''': You must make backups of your database before attempting to change any MySQL server configuration. After any change to the my.cnf, restart mysqld.

If you are able, the [http://mysqltuner.com/ MySQLTuner] tool can be run against your MySQL server and will calculate appropriate configuration values for most of the following settings based on your current load, status and variables automatically.

* Enable the '''query cache''' with
query_cache_type = 1.
For most Moodle installs, set the following:
query_cache_size = 36M
query_cache_min_res_unit = 2K.
The query cache will improve performance if you are doing few updates on the database.
* Set the '''table cache''' correctly. For Moodle 1.6 set
table_cache = 256 #(table_open_cache in MySQL > 5.1.2)
(min), and for Moodle 1.7 set
table_cache = 512 #(table_open_cache in MySQL > 5.1.2)
(min). The table cache is used by all threads (connections), so monitor the value of opened_tables to further adjust - if opened_tables > 3 * table_cache(table_open_cache in MySQL > 5.1.2) then increase table_cache upto your OS limit. Note also that the figure for table_cache will also change depending on the number of modules and plugins you have installed. Find the number for your server by executing the mysql statement below. Look at the number returned and set table_cache to this value.
mysql>SELECT COUNT(table_name) FROM information_schema.tables WHERE table_schema='yourmoodledbname';
* Set the '''thread cache''' correctly. Adjust the value so that your thread cache utilization is as close to 100% as possible by this formula:
thread cache utilization (%) = (threads_created / connections) * 100
* The '''key buffer''' can improve the access speed to Moodle's SELECT queries. The correct size depends on the size of the index files (.myi) and in Moodle 1.6 or later (without any additional modules and plugins), the recommendation for this value is key_buffer_size = 32M. Ideally you want the database to be reading once from the disk for every 100 requests so monitor that the value is suitable for your install by adjusting the value of key_buffer_size so that the following formulas are true:
key_read / key_read_requests < 0.01
key_write / key_write_requests <= 1.0
* Set the '''maximum number of connections''' so that your users will not see a "Too many connections" message. Be careful that this may have an impact on the total memory used. MySQL connections usually last for milliseconds, so it is unusual even for a heavily loaded server for this value to be over 200.
* Manage '''high burst activity'''. If your Moodle install uses a lot of quizzes and you are experiencing performance problems (check by monitoring the value of threads_connected - it should not be rising) consider increasing the value of back_log.
* '''Optimize your tables weekly and after upgrading Moodle'''. It is good practice to also optimize your tables after performing a large data deletion exercise, e.g. at the end of your semester or academic year. This will ensure that index files are up to date. Backup your database first and then use:
mysql>CHECK TABLE mdl_tablename;
mysql>OPTIMIZE TABLE mdl_tablename;
:The common tables in Moodle to check are mdl_course_sections, mdl_forum_posts, mdl_log and mdl_sessions (if using dbsessions). Any errors need to be corrected using REPAIR TABLE (see the [http://dev.mysql.com/doc/refman/5.0/en/repair-table.html MySQL manual] and this [http://moodle.org/mod/forum/discuss.php?d=58208#p279638 forum script]).
* '''Maintain the key distribution'''. Every month or so it is a good idea to stop the mysql server and run these myisamchk commands.
#myisamchk -a -S /pathtomysql/data/moodledir/*.MYI
:'''Warning''': You must stop the mysql database process (mysqld) before running any myisamchk command. If you do not, you risk data loss.
* Reduce the number of '''temporary tables saved to disk'''. Check this with the created_tmp_disk_tables value. If this is relatively large (>5%) increase tmp_table_size until you see a reduction. Note that this will have an impact on RAM usage.

===PostgreSQL performance===

There are some good papers around on tuning PostgreSQL, and Moodle's case does not seem to be different to the general case.

The first thing to recognise is that if you really need to worry about tuning you should be using a separate machine for the database server. If you are not using a separate machine then the answers to many performance questions are substantially muddied by the memory requirements of the rest of the application.

You should probably '''enable autovacuum''', unless you know what you are doing. Many e-learning sites have predictable periods of low use, so disabling autovacuum and running a specific vacuum at those times can be a good option. Or perhaps leave autovacuum running but do a full vacuum weekly in a quiet period.

Set '''shared_buffers''' to something reasonable. For versions up to 8.1 my testing has shown that peak performance is almost always obtained with buffers < 10000, so if you are using such a version, and have more than 512M of RAM just set shared_buffers to 10,000 (8MB).

The buffer management had a big overhaul in 8.2 and "reasonable" is now a much larger number. I have not conducted performance tests with 8.2, but the recommendations from others are generally that you should now scale shared_buffers much more with memory and may continue to reap benefits even up to values like 100,000 (80MB). Consider using 1-2% of system RAM.

PostgreSQL will also assume that the operating system is caching its files, so setting '''effective_cache_size''' to a reasonable value is also a good idea. A reasonable value will usually be (total RAM - RAM in use by programs). If you are running Linux and leave the system running for a day or two you can look at 'free' and under the 'cached' column you will see what it currently is. Consider taking that number (which is kB) and dividing it by 10 (i.e. allow 20% for other programs cache needs and then divide by 8 to get pages). If you are not using a dedicated database server you will need to decrease that value to account for usage by other programs.

Some other useful parameters that can have positive effects, and the values I would typically set them to on a machine with 4G RAM, are:

work_mem = 10240

That's 10M of RAM to use instead of on-disk sorting and so forth. That can give a big speed increase, but it is per connection and 200 connections * 10M is 2G, so it can theoretically chew up a lot of RAM.

maintenance_work_mem = 163840

That's 160M of RAM which will be used by (e.g.) VACUUM, index rebuild, cluster and so forth. This should only be used periodically and should be freed when those processes exit, so I believe it is well worth while.

max_fsm_pages = 100000
max_fsm_relations = 5000

These are used to hold the free-space map, and if they are too small you will see performance degradation after the database has been operating for some time. The exact numbers to set can be gleaned from the output of VACUUM VERBOSE, which prints the required FSM pages at the end of it's run. The 5x increase seems to be useful for a Moodle installation, from experience.

wal_buffers = 64

These buffers are used for the write-ahead log, and there have been a number of reports on the PostgreSQL mailing lists of improvement from this level of increase.

This is a little out of date now (version 8.0) but still worth a read: http://www.powerpostgresql.com/Docs

And there is lots of good stuff here as well: http://www.varlena.com/GeneralBits/Tidbits/index.php

''Based on Andrew McMillan's post at [http://moodle.org/mod/forum/discuss.php?d=68558 Tuning PostgreSQL] forum thread.''

===Other database performance links===
* Consider using a '''distributed cacheing system''' like [http://en.wikipedia.org/wiki/Memcached memcached] but note that memcached does not have any security features so it should be used behind a firewall.
* Consider using PostgreSQL. See [[Arguments in favour of PostgreSQL]] and [http://moodle.org/mod/forum/discuss.php?d=49195 how to migrate from MySQL to PostgreSQL] (forum discussion).
* [[Increasing the database connection lifetime | Try increasing the database connection lifetime]]
* [http://dev.mysql.com/doc/refman/5.0/en/server-parameters.html General advice on tuning MySQL parameters] (advice from the MySQL manual)
* [http://www.mysqlperformanceblog.com/2007/11/01/innodb-performance-optimization-basics/ InnoDB performance optimization] taken from the [http://www.mysqlperformanceblog.com/ MySQL performance blog] site.

==Moodle Admin settings==
* In Moodle 1.7 or later, set the '''Cache type''' for your server: Site Admin -> Server -> Performance -> Cache type. There are several options available.
:*If you do not have eaccelerator or mmemcached installed, choose "internal" (which makes use of the record/internal cache - see the next bullet point).
:* If you have a single server and have compiled '''eaccelerator with shared memory support''', set the cache type to the eaccelerator option.
:* If you have a '''separate memcached server''', set the cache type to memcached and enter a csv list of server IP addresses.
* Enable the '''record/internal cache''': Site Admin -> Server -> Performance -> Record cache = True. Set the maximum amount of memory allocated to the cache in the Int Cache Max box. This will enable a primary cache for database records, without using any database engine cache, e.g. MySQL/PostgreSQL cache. See [http://tracker.moodle.org/browse/MDL-7196 this Tracker entry] for a full discussion.
* Enable the '''language cache'''.
* Large log files can cause overall performance to degrade over time. If you observe that the site has gradually got slower loading pages in the browser, '''reduce your Log life time''' setting (Admin/Server/Cleanup).
* Performance can be greatly improved by allowing Moodle to use the system '''zip/unzip''' commands (rather than PHP-based zip libraries) - visit Admin/Server/System Paths and enter the path to the relevant executables. (Similarly, filling in the path to '''du''' will improve Moodle's speed at listing directory contents.)
* Note that using '''secure web connections''' ('''https''' rather than '''http''') carries a higher processing burden, both for the webserver and the client - particularly because cacheing cannot be used as effectively, so the number of file requests is likely to increase dramatically. For this reason using https for all Moodle pages is not recommended. You can enable https just for the login screen, simply from Moodle's config page.
* Check your '''filters'''. Having too many filters active can have serious effects on server load, especially on lower-end systems. The number of active filters has a direct effect on the perceived latency of your site; that is the time taken for each page impression.
* Enable the '''text cache''' but do not "Filter all strings" unless you have a specific need. If in doubt profile the performance, and see how your changes affect the processing time.
* Check your '''anti-virus''' measures on the server. Although they are useful for preventing security holes being exploited, some "On-Demand" scanners can affect performance by scanning page content (word, ppt files etc).
* If there are performance problems loading course pages, check the '''Resource module settings'''. The setting resource_filterexternalpages is known to slow-down course pages and should be set to 'No' for better performance.
* Check your '''forum settings'''. To improve performance set forum_trackreadposts = No and forum_usermarksread = Yes (this will impact on the convenience of your users' forum experience). Also consider setting the time of the day when old posts are cleared from the read table (forum_cleanreadtime) to when your site is less busy.
* Don't use database sessions unless you really need them. On-disc sessions tend to be much faster.

==Performance of different Moodle modules==

Moodle's activity modules, filters, and other plugins can be activated/deactivated. If necessary, you may wish to deactivate some features (such as chat) if not required - but this isn't necessary. Some notes on the performance of certain modules:

* The '''Chat''' module is [http://moodle.org/mod/forum/discuss.php?d=37979&parent=175079 said] to be a hog in terms of frequent HTTP requests to the main server. This can be reduced by setting the module to use ''Streamed'' updates, or, if you're using a Unix-based webserver, by running the chat in daemon mode. When using the Chat module use the configuration settings to tune for your expected load. Pay particular attention to the ''chat_old_ping'' and ''chat_refresh'' parameters as these can have greatest impact on server load.
* The '''Quiz''' module is known to stretch database performance. Try to optimise your database server by tuning. See [http://moodle.org/mod/forum/discuss.php?d=25616&parent=120770 for a brief report on performance for 55 students simultaneously using quizzes]
** See this Case Study for an extensive server stress test with 300 quiz users.[http://moodle.org/mod/forum/discuss.php?d=68579] And this accompanying report on network traffic and server loads. [http://elearning.sgu.ac.jp/doc/PT/]
* The Moodle '''Cron''' task is triggered by calling the script ''cron.php''. If this is called over HTTP (e.g. using wget or curl) it can take a large amount of memory on large installations. If it is called by directly invoking the php command (e.g. ''php -f /path/to/moodle/directory/admin/cron.php'') efficiency can be much improved.
* The '''Recent activities''' block is consuming to much resources if you have huge number of records <code>mdl_log</code>. this is being tested to optimize the SQL query.

==Moodle Image Optimization==

The base images delivered in the original Moodle distribution package provide unoptimized graphics, most of which can benefit from lossless recompression utilizing [http://optipng.sourceforge.net/ optipng] for PNGs, [http://www.lcdf.org/gifsicle/ gifsicle] for GIFs and [http://www.kokkonen.net/tjko/projects.html jpegoptim] for JPGs. Optimized graphics transfer faster and provide a faster perceived response for clients[http://www.websiteoptimization.com/speed/12/], especially distance learners. The following example will recursively optimize (without any loss of quality) all the graphics and image files included in a base Moodle installation directory on a server with the above commands installed and available.

<pre>
find /example/directory/moodle-1.9 -iname *.png -exec optipng -o7 {} \;
find /example/directory/moodle-1.9 -iname *.gif -exec gifsicle -O2 -b {} \;
find /example/directory/moodle-1.9 -iname *.jpg -exec jpegoptim -p {} \;
</pre>

Both [http://optipng.sourceforge.net/ optipng] and [http://www.lcdf.org/gifsicle/ gifsicle] are provided in the base repositories of most newer Linux distributions; [http://www.kokkonen.net/tjko/projects.html jpegoptim] must be downloaded and installed manually.

==See also==

*[[Performance FAQ]]
*Using Moodle: [http://moodle.org/mod/forum/view.php?f=94 Hardware and Performance] forum

There have been a lot of discussions on moodle.org about performance, here are some of the more interesting and (potentially) useful ones:

* [http://moodle.org/mod/forum/discuss.php?d=83057 Performance woes!]
* [http://moodle.org/mod/forum/discuss.php?d=57028 Performance perspectives - a little script]
* [http://moodle.org/mod/forum/discuss.php?d=88927 Comments on planned server hardware]
* [http://moodle.org/mod/forum/discuss.php?d=102978#p461624 Moodle performance in a pil by Martin Langhoff]
[[Category:Performance]]

[[es:Rendimiento]]
[[fr:Performance]]
[[ja:パフォーマンス]]
[[pl:Wydajnosc]]

Development:lib/formslib.php Form Definition

2011-05-03T10:21:41Z

Marxjohnson: Added note to Choosecoursefile to indicate that Moodle 2 now uses filepicker

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform =& $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with a couple of important improvements:

# The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[Development:lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.

=== choosecoursefile ===
{{Moodle 1.9}}
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

'''Note: This has been superseded by [[#filepicker|filepicker]] in Moodle 2.'''

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$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->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Development:Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

<code php>
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</code>

You can supply a fourth param to htmleditor of an array of options :

<code php>

array(
'canUseHtmlEditor'=>'detect',
'rows' => 10,
'cols' => 65,
'width' => 0,
'height'=> 0,
'course'=> 0,
);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</code>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===

<code php>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

====multi-select====
<pre>
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

==setHelpButton==
{{Moodle 1.9}}

<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==addHelpButton==
{{Moodle 2.0}}

<pre>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</pre>

In Moodle 2.0 the "setHelpButton" method has been deprecated in favor of the "addHelpButton" method, which has a simplified interface and uses $OUTPUT->help_icon() on the back end. The following parameters are expected:

* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in

Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:

1. get_string($identifier, $component): The title of the help page
2. get_string("{$identifier}_help", $component): The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

The possible choices here are in the function lockoptionsall in lib/javascript-static.js.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]

If you have problems creating php forms you may get them with form builder http://phpforms.net/tutorial/html-basics/form-builder.html

Development:Subplugins

2011-03-23T13:45:52Z

Marxjohnson: Fixed transposed parameters in example.

Sub plugins allow activity modules to be extended without having to change the module's code.

Each activity module can define a set of subplugin types in <tt>db/subplugins.php</tt>. The file must contain an array called <tt>$subplugins</tt>, with the plugin type as the key for the directory containing the plugins. For example, from <tt>mod/workshop/db/subplugins.php</tt>:
$subplugins = array(
'workshopform' => 'mod/workshop/form',
'workshopallocation' => 'mod/workshop/allocation',
'workshopeval' => 'mod/workshop/eval',
);
This defines 3 plugin types, <tt>workshopform</tt>, <tt>workshopallocation</tt>, and <tt>workshopeval</tt>. The plugins themselves can be found in <tt>mod/workshop/form</tt>, <tt>mod/workshop/allocation</tt> and <tt>mod/workshop/eval</tt>, respectively. Each of these directories can contain a number of plugins, each within it's own subdirectory.

=== Writing a sub-plugin ===
A sub-plugin has the same structure as a regular plugin. It will have a <tt>version.php</tt>, a <tt>lang</tt> directory, and can have a <tt>db</tt> directory with an <tt>install.xml</tt> and all the other hooks you'd expect to see used in any other type of plugin, such as an activity, block, or admin report.

An important thing to remember when using lang strings is to prefix the component with the plugin type, as you do with all non-activity blocks. So to print the name of the "accumulative" workshopform plugin, you'd do
print_string('pluginname', 'workshopform_accumulative');

Development:Subplugins

2011-03-23T13:45:07Z

Marxjohnson: New page: Sub plugins allow activity modules to be extended without having to change the module's code. Each activity module can define a set of subplugin types in <tt>db/subplugins.php</tt>. The ...

Development:Developer documentation

2011-03-23T13:34:41Z

Marxjohnson: /* Make a new plugin */

[[image:moodle-development-logo.jpg|right|400px]]

This [[:Category:Developer|Developer]] section of Moodle Docs is aimed at developers who contribute to the Moodle code, plugins, themes, and so on.

* If you manage a Moodle site, [[Administrator documentation]] may suit your needs better.
* If you teach using Moodle, try [[Teacher documentation]].
<br />
<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches.<br /><br />

A page may be added to the Developer category by adding the template <code><nowiki>{{CategoryDeveloper}}</nowiki></code> to the bottom of the page. - If required, you can use <code><nowiki>[[Category:Developer|Sort key]]</nowiki></code> to provide a sort key other than the default page name.</p>

==How Moodle development works==

The [[Development:Overview|overview of the Moodle development process]] explains how Moodle development occurs and how people become Moodle developers. Current plans are listed on the [[Roadmap]].

You can also enrol in one of the [http://dev.moodle.org Moodle Developer Courses].

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Development:Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle architecture]] gives an overview of how the Moodle code works
*[[Development:Process]] explains how changes are incorporated into Moodle
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Development:Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Development:Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Development:Profiling PHP|Profiling PHP]] how to analyse your code to find out why it is slow.
*[[Development:Fast portable SQL]] shows SQL techniques that are fast, efficient, and known to work on all supported DBs.
*[[Development:Development hints and tips]] a (developing) list of general wisdom to help with your Moodle projects.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Development:Developer notes|developer notes]] or on the [[Roadmap|roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code.

And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online] using [[Development:PHPXref|PHPXref]].

===Core components ===

*[[Development:XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Development:Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what
*[[Development:lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things
*[[Development:Using_the_file_API|File API]] @ v[[2.0]] for managing files stored by Moodle
*[[Development:Database schema introduction|The database schema]]
*[[Development:What happens when you require config.php|What happens when you require config.php]]
*[[Development:lib/moodlelib.php|lib/moodlelib.php]]
*[[Development:lib/weblib.php|lib/weblib.php]] for outputting stuff

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Development:Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Development:Groups|Groups system]]
*[[Development:Grades|Gradebook]]
*[[Development:Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[Development:lib/graphlib|lib/graphlib]]
*[[Development:Admin settings|Admin settings]]

===Modules included in the standard distribution===

*[[Development:Lesson Specification|Lesson Specification]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Development:Modules|Activity modules]], see also [[Development:NEWMODULE Documentation]] (work in progress)
**and [[Development:Subplugins|Sub-Plugins]] (2.0 Onwards)
*[[Development:Admin reports|Admin reports]]
*[[Development:Assignment types|Assignment types]]
*[[Development:Authentication plugins|Authentication plugins]]
*[[Development:Blocks|Blocks]]
*Content editors (2.0 onwards)
*[[Course formats]]
*[[Development:Course Report Plugins|Course reports]]
*Course importers (2.0 onwards)
*[[Development:Database fields|Database fields]]
*[[Development:Database presets|Database presets]]
*[[Development:Enrolment plugins|Enrolment plugins]]
*[[Development:Filters|Filters]]
*[[Development:Gradebook_Report_Tutorial|Gradebook report]]
*[[Development:Gradebook export|Gradebook export]]
*[[Development:Gradebook import|Gradebook import]]
*Message senders (2.0 onwards)
*Mnet services
*Plagiarism detection plugins (2.0 onwards)
*[[Development:Writing_a_Portfolio_Plugin|Portfolio plugins]] (2.0 onwards)
*[[Development:Question_type_plugin_how_to|Question types]]
*[[Development:Question import/export formats|Question import/export formats]]
*[[Development:How to write a quiz report plugin|Quiz reports]]
*[[Development:Repository plugins|Repository plugins]] (2.0 onwards)
*[[Development:Resource types|Resource types]]
*[[Development:Search engine adapters|Search engine adapters]]
*Themes which are different in [[Development:Themes_2.0|Moodle 2.0]], and [[Theme_basics|earlier versions]].
*User profile fields
*[[Development:Web services (2.0 onwards)|Web services (2.0 onwards)]]
*Workshop allocators (2.0 onwards)
*Workshop forms (2.0 onwards)
*Workshop evaluators (2.0 onwards)

General information that applies to all types of plugins
*[[Development:Places to search for lang strings|Where to put language strings for your plugin]]
*[[Development:Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

Please see the [[Development:Guidelines for contributed code|Guidelines for contributed code]] for an overview of how to contribute to the Moodle code.

Sometimes it is not possible to write a proper plugin for what you want to do, in which case you may have to resort to using the [[Development:Local_customisation|local customisations]] hook.

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[Development:How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first. See [[Development:Overview#Major_Development]] for more details.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Development:Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap|roadmap]] or in the form of [[Development:Developer notes|developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Development:Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer meetings]]

== Resources ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Development:Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
**[[Firefox tracker search#Firefox Search Plugins|Firefox Search Plugins]] - Find tracked issues even more easily
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to [[HEAD]]
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled nightly from the comment attached to each class and function in the code.
*[[Development:Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]

== Tools ==
Some tools people use when working on Moodle code:

=== IDEs ===

* [[Development:Setting_up_Netbeans|Setting up NetBeans for Moodle development]] - NetBeans for PHP is a great out-of-the-box editor.
* [[Development:Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
* [[Development:vim|Setting up Vim for Moodle development]]
* [http://www.aptana.com/ Aptana Studio 2]

=== Browser add-ons ===
*[http://getfirebug.com Firebug], see [[Firebug]] for details.
* [[Web developer extension]]
* [https://addons.mozilla.org/en-US/firefox/addon/394 ViewSourceWith] - The main goal is to view page source with external applications, but you can do a lot of other things as well.

=== Miscellaneous ===
*[[Development:ctags|Ctags]] - Using a tags file to navigate code
*[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
*[[Development:Windows Installer|Windows Installer]] - Windows Installer documentation for developer.

See also: [http://dev.moodle.org/mod/forum/view.php?id=18 Useful Development Tools forum]in the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming course]

==See also==

*[http://moodle.org/security/ Moodle Security Announcements]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[Category:Developer]]
[[Category:Developer tools]]

[[ru:Development:Краткий обзор]]
[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[pt:Desenvolvimento:Documentação para programadores]]
[[zh:开发者文档]]
[[ja:開発者ドキュメント]]
[[fi:Ohjelmoijan opas]]

Development:Developer documentation

2011-03-23T13:34:18Z

Marxjohnson: /* Make a new plugin */

[[image:moodle-development-logo.jpg|right|400px]]

This [[:Category:Developer|Developer]] section of Moodle Docs is aimed at developers who contribute to the Moodle code, plugins, themes, and so on.

* If you manage a Moodle site, [[Administrator documentation]] may suit your needs better.
* If you teach using Moodle, try [[Teacher documentation]].
<br />
<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches.<br /><br />

A page may be added to the Developer category by adding the template <code><nowiki>{{CategoryDeveloper}}</nowiki></code> to the bottom of the page. - If required, you can use <code><nowiki>[[Category:Developer|Sort key]]</nowiki></code> to provide a sort key other than the default page name.</p>

==How Moodle development works==

The [[Development:Overview|overview of the Moodle development process]] explains how Moodle development occurs and how people become Moodle developers. Current plans are listed on the [[Roadmap]].

You can also enrol in one of the [http://dev.moodle.org Moodle Developer Courses].

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Development:Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle architecture]] gives an overview of how the Moodle code works
*[[Development:Process]] explains how changes are incorporated into Moodle
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Development:Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Development:Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Development:Profiling PHP|Profiling PHP]] how to analyse your code to find out why it is slow.
*[[Development:Fast portable SQL]] shows SQL techniques that are fast, efficient, and known to work on all supported DBs.
*[[Development:Development hints and tips]] a (developing) list of general wisdom to help with your Moodle projects.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Development:Developer notes|developer notes]] or on the [[Roadmap|roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code.

And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online] using [[Development:PHPXref|PHPXref]].

===Core components ===

*[[Development:XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Development:Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what
*[[Development:lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things
*[[Development:Using_the_file_API|File API]] @ v[[2.0]] for managing files stored by Moodle
*[[Development:Database schema introduction|The database schema]]
*[[Development:What happens when you require config.php|What happens when you require config.php]]
*[[Development:lib/moodlelib.php|lib/moodlelib.php]]
*[[Development:lib/weblib.php|lib/weblib.php]] for outputting stuff

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Development:Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Development:Groups|Groups system]]
*[[Development:Grades|Gradebook]]
*[[Development:Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[Development:lib/graphlib|lib/graphlib]]
*[[Development:Admin settings|Admin settings]]

===Modules included in the standard distribution===

*[[Development:Lesson Specification|Lesson Specification]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Development:Modules|Activity modules]], see also [[Development:NEWMODULE Documentation]] (work in progress)
**and [[Development:Subplugins|Sub-Plugins]]
*[[Development:Admin reports|Admin reports]]
*[[Development:Assignment types|Assignment types]]
*[[Development:Authentication plugins|Authentication plugins]]
*[[Development:Blocks|Blocks]]
*Content editors (2.0 onwards)
*[[Course formats]]
*[[Development:Course Report Plugins|Course reports]]
*Course importers (2.0 onwards)
*[[Development:Database fields|Database fields]]
*[[Development:Database presets|Database presets]]
*[[Development:Enrolment plugins|Enrolment plugins]]
*[[Development:Filters|Filters]]
*[[Development:Gradebook_Report_Tutorial|Gradebook report]]
*[[Development:Gradebook export|Gradebook export]]
*[[Development:Gradebook import|Gradebook import]]
*Message senders (2.0 onwards)
*Mnet services
*Plagiarism detection plugins (2.0 onwards)
*[[Development:Writing_a_Portfolio_Plugin|Portfolio plugins]] (2.0 onwards)
*[[Development:Question_type_plugin_how_to|Question types]]
*[[Development:Question import/export formats|Question import/export formats]]
*[[Development:How to write a quiz report plugin|Quiz reports]]
*[[Development:Repository plugins|Repository plugins]] (2.0 onwards)
*[[Development:Resource types|Resource types]]
*[[Development:Search engine adapters|Search engine adapters]]
*Themes which are different in [[Development:Themes_2.0|Moodle 2.0]], and [[Theme_basics|earlier versions]].
*User profile fields
*[[Development:Web services (2.0 onwards)|Web services (2.0 onwards)]]
*Workshop allocators (2.0 onwards)
*Workshop forms (2.0 onwards)
*Workshop evaluators (2.0 onwards)

General information that applies to all types of plugins
*[[Development:Places to search for lang strings|Where to put language strings for your plugin]]
*[[Development:Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

Please see the [[Development:Guidelines for contributed code|Guidelines for contributed code]] for an overview of how to contribute to the Moodle code.

Sometimes it is not possible to write a proper plugin for what you want to do, in which case you may have to resort to using the [[Development:Local_customisation|local customisations]] hook.

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[Development:How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first. See [[Development:Overview#Major_Development]] for more details.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Development:Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap|roadmap]] or in the form of [[Development:Developer notes|developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Development:Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer meetings]]

== Resources ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Development:Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
**[[Firefox tracker search#Firefox Search Plugins|Firefox Search Plugins]] - Find tracked issues even more easily
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to [[HEAD]]
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled nightly from the comment attached to each class and function in the code.
*[[Development:Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]

== Tools ==
Some tools people use when working on Moodle code:

=== IDEs ===

* [[Development:Setting_up_Netbeans|Setting up NetBeans for Moodle development]] - NetBeans for PHP is a great out-of-the-box editor.
* [[Development:Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
* [[Development:vim|Setting up Vim for Moodle development]]
* [http://www.aptana.com/ Aptana Studio 2]

=== Browser add-ons ===
*[http://getfirebug.com Firebug], see [[Firebug]] for details.
* [[Web developer extension]]
* [https://addons.mozilla.org/en-US/firefox/addon/394 ViewSourceWith] - The main goal is to view page source with external applications, but you can do a lot of other things as well.

=== Miscellaneous ===
*[[Development:ctags|Ctags]] - Using a tags file to navigate code
*[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
*[[Development:Windows Installer|Windows Installer]] - Windows Installer documentation for developer.

See also: [http://dev.moodle.org/mod/forum/view.php?id=18 Useful Development Tools forum]in the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming course]

==See also==

*[http://moodle.org/security/ Moodle Security Announcements]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[Category:Developer]]
[[Category:Developer tools]]

[[ru:Development:Краткий обзор]]
[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[pt:Desenvolvimento:Documentação para programadores]]
[[zh:开发者文档]]
[[ja:開発者ドキュメント]]
[[fi:Ohjelmoijan opas]]

Maintaining Moodle customisations with Git

2011-03-15T11:31:57Z

Marxjohnson:

'''This page is a work in progress'''

Git makes it very easy to maintain local customisations to Moodle alongside updates from the official Moodle repository.
This page assumes you installed Moodle following [[Installing Moodle from Git repository]]. It also assumes you understand basic version control principles (repositories, branches, conflicts) and have a basic working knowledge of Git.

First, from your moodle directory, create a branch of <tt>master</tt> which will contain your customised Moodle. This is the branch you'll publish to other servers.
git checkout master
git checkout -b mycustommoodle

Switched to a new branch 'mycustommoodle'
Next, create a new branch for developing your customisation, and move to that branch:
git checkout -b myfeature

Switched to a new branch 'myfeature'
This will give you a seperate copy of the Moodle code to work on without affecting the master branch. It's not recommended that you do this on your production server, as it will cause the code to be available immediately as it's saved.

Do your customisations, add any new files to git, and commit the changes
git add .
git status
git commit -m "Description of the change"

Switch back to the <tt>mycustommoodle</tt> branch and merge the changes
git checkout mycustommoodle
git merge myfeature
Any future development can take place on the myfeature branch, and be merged into mycustommoodle in this way

Even after local modifications have been made, you can pull in updates from the official git repository
git checkout master
git fetch
git merge origin/master
git checkout mycustommoodle
git merge master

=== Conflicts ===
If you create a local modification to a file, and that same file is modified in the official repository, you may find that a conflict is created when you do <tt>git merge origin/master</tt>.

To resolve this, you will need to find the conflicts (the attempt to merge will tell you where they are) and resolve them. The [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html|<tt>git merge</tt> man page] has more information on the presentation and resolution of conflicts.

After the conflict is resolved, you'll need to commit the resolved files.
git commit -a
Once a conflict has been resolved, even if you keep your local modification over the upstream modification, there wont be a conflict next time you merge.

Git repositories for contrib modules

2011-03-15T09:37:45Z

Marxjohnson: /* Installing a third-party plugin */

'''This page is a work in progress.''' The instructions here assume that you have a working knowledge of git.

Managing contrib plugin with git makes it easy to make local modifications and pull in updates.
There are several options for managing a contrib plugin with git:
# Add the module to your main moodle git repository
# Create a self-contained repository for the plugin in a subdirectory
# Create a git submodule, which creates a repository for the plugin but tracks updates in the main repository too. It also allows you to clone the plugins with the main repository
Having used all of the above, the method I'd recommend is number 2, as it's most convenient. The main disadvantage of 1 is that you can't easily pull in updates, and the main disadvantage of 3 is that you have to make each commit to the module twice (once in the submodule, and once in the main repo).

== Creating a new plugin ==
If you intend to publish the plugin, I highly recommend creating a [http://github.org github] repository from the start. This will allow you to publish with a single command when you're ready. Just go to the site, sign up for an account, create a new repository. The naming convention for Moodle plugin repositories is <tt>moodle-plugintype_pluginname</tt>.

Github will give you instructions for cloning your (blank) repository. If you're using option 2 above, navigate to the directory for the plugin type you're developing (e.g. /block, /mod, /local) and run the <tt>git clone</tt> command there. This will create a subdirectory called <tt>moodle-plugintype_pluginname</tt>, rename this to <tt>pluginname</tt> and you're good to go. <tt>cd</tt> into this directory to perform git commands on this plugin's repository - outside of this directory will perform them on the main Moodle repository.

You can then develop and test your changes locally, and when you're ready to publish, run
git push origin

== Installing a third-party plugin ==
Installing a plugin developed by a third party differs depending on whether they have used git or not.
If they have used git, you can follow the instructions above, but skip out the part where you create a new github repository and clone their own github (or other public repository) instead.

If they haven't used git, you can still use git (and even github, if you like) to track local modifications to the plugin. Simply create a directory for the plugin
mkdir ~/moodle/blocks/newblock
Initialise a new git repository there
cd ~/moodle/blocks/newblock
git init
unzip or copy the files to the repository
cd ~
tar -xf newblock.tar.gz
cp newblock/* ~/moodle/blocks/newblock
add and commit the files
cd ~/moodle/blocks/newblock
git add .
git commit . -m "Added files for newblock"
When installing updates, you'll need to copy the new files in place of the old one, and re run the <tt>git add</tt> and <tt>git commit</tt> commands.

== Moving a plugin to it's own repository ==
You may have developed a plugin within your main Moodle repository, but want to move it to a separate one to make it easier to publish. Using <tt>git filter-branch</tt>, we can achieve this and maintain all existing history for the plugin's files.

First, you'll need a fresh copy of moodle (this will become your new moodle repository)
mkdir ~/newmoodle
cd ~/newmoodle
git clone git://git.moodle.org/moodle.git
This will create a clone of Moodle without your plugins in ~/newmoodle/moodle
Next, you need to clone your local Moodle repository (why will become clear).
mkdir ~/moodleclone
cd ~/moodleclone
git clone ~/moodle
This will create a clone of your current moodle development repository, with your plugins, in ~/moodleclone/moodle
Now, we'll use the <tt>git filter-branch</tt> command to reduce this clone to just the plugin.
cd ~/moodleclone/moodle
git filter-branch --subdirectory-filter blocks/myblock/
The files from blocks/myblock/ will now be at the root of the repository. All other files will have been removed (this is why we're using a clone).
You can now track the plugin in it's own repository by cloning this reduced repository to a subdirectory of the new moodle clone.
cd ~/newmoodle/blocks
git clone ~/moodleclone/moodle myblock
This will clone the block's files, with the full history, into their own repository in the myblock subdirectory.
You can now delete ~/moodleclone/moodle, and repeat with any other plugins you've developed.

Git repositories for contrib modules

2011-03-15T09:36:21Z

Marxjohnson:

'''This page is a work in progress.''' The instructions here assume that you have a working knowledge of git.

Managing contrib plugin with git makes it easy to make local modifications and pull in updates.
There are several options for managing a contrib plugin with git:
# Add the module to your main moodle git repository
# Create a self-contained repository for the plugin in a subdirectory
# Create a git submodule, which creates a repository for the plugin but tracks updates in the main repository too. It also allows you to clone the plugins with the main repository
Having used all of the above, the method I'd recommend is number 2, as it's most convenient. The main disadvantage of 1 is that you can't easily pull in updates, and the main disadvantage of 3 is that you have to make each commit to the module twice (once in the submodule, and once in the main repo).

== Creating a new plugin ==
If you intend to publish the plugin, I highly recommend creating a [http://github.org github] repository from the start. This will allow you to publish with a single command when you're ready. Just go to the site, sign up for an account, create a new repository. The naming convention for Moodle plugin repositories is <tt>moodle-plugintype_pluginname</tt>.

Github will give you instructions for cloning your (blank) repository. If you're using option 2 above, navigate to the directory for the plugin type you're developing (e.g. /block, /mod, /local) and run the <tt>git clone</tt> command there. This will create a subdirectory called <tt>moodle-plugintype_pluginname</tt>, rename this to <tt>pluginname</tt> and you're good to go. <tt>cd</tt> into this directory to perform git commands on this plugin's repository - outside of this directory will perform them on the main Moodle repository.

You can then develop and test your changes locally, and when you're ready to publish, run
git push origin

== Installing a third-party plugin ==
Installing a plugin developed by a third party differs depending on whether they have used git or not.
If they have used git, you can follow the instructions above, but skip out the part where you create a new repository and clone their own git repository instead.

If they haven't used git, you can still use git (and even github, if you like) to track local modifications to the plugin. Simply create a directory for the plugin
mkdir ~/moodle/blocks/newblock
Initialise a new git repository there
cd ~/moodle/blocks/newblock
git init
unzip or copy the files to the repository
cd ~
tar -xf newblock.tar.gz
cp newblock/* ~/moodle/blocks/newblock
add and commit the files
cd ~/moodle/blocks/newblock
git add .
git commit . -m "Added files for newblock"
When installing updates, you'll need to copy the new files in place of the old one, and re run the <tt>git add</tt> and <tt>git commit</tt> commands.

== Moving a plugin to it's own repository ==
You may have developed a plugin within your main Moodle repository, but want to move it to a separate one to make it easier to publish. Using <tt>git filter-branch</tt>, we can achieve this and maintain all existing history for the plugin's files.

First, you'll need a fresh copy of moodle (this will become your new moodle repository)
mkdir ~/newmoodle
cd ~/newmoodle
git clone git://git.moodle.org/moodle.git
This will create a clone of Moodle without your plugins in ~/newmoodle/moodle
Next, you need to clone your local Moodle repository (why will become clear).
mkdir ~/moodleclone
cd ~/moodleclone
git clone ~/moodle
This will create a clone of your current moodle development repository, with your plugins, in ~/moodleclone/moodle
Now, we'll use the <tt>git filter-branch</tt> command to reduce this clone to just the plugin.
cd ~/moodleclone/moodle
git filter-branch --subdirectory-filter blocks/myblock/
The files from blocks/myblock/ will now be at the root of the repository. All other files will have been removed (this is why we're using a clone).
You can now track the plugin in it's own repository by cloning this reduced repository to a subdirectory of the new moodle clone.
cd ~/newmoodle/blocks
git clone ~/moodleclone/moodle myblock
This will clone the block's files, with the full history, into their own repository in the myblock subdirectory.
You can now delete ~/moodleclone/moodle, and repeat with any other plugins you've developed.

Maintaining Moodle customisations with Git

2011-03-15T09:33:38Z

Marxjohnson:

'''This page is a work in progress'''

Git makes it very easy to maintain local customisations to Moodle alongside updates from the official Moodle repository.
This page assumes you installed Moodle following [[Installing Moodle from Git repository]]. It also assumes you understand basic version control principles (repositories, branches, conflicts) and have a basic working knowledge of Git.

From your moodle directory, create a new branch for developing your customisation, and move to that branch:
git checkout -b myfeature

Switched to a new branch 'myfeature'
This will give you a seperate copy of the Moodle code to work on without affecting the master branch. It's not recommended that you do this on your production server, as it will cause the code to be available immediately as it's saved.

Do your customisations, add any new files to git, and commit the changes
git add .
git status
git commit -m "Description of the change"

''Ouch! this next bit is a really bad idea. I don't know what you are trying to achieve, but this is not the right way to do it!!!--[[User:Tim Hunt|Tim Hunt]] 09:09, 15 March 2011 (UTC)''

''Please edit it to the right way to do it then, it hasn't caused me any problems (yet) :-)[[User:Mark Johnson|Mark Johnson]]''

Switch back to the master branch and merge the changes
git checkout master
git merge myfeature
Any future development can take place on the myfeature branch, and be merged into master in this way

Even after local modifications have been made, you can pull in updates from the official git repository
git checkout master
git fetch
git merge origin/master

=== Conflicts ===
If you create a local modification to a file, and that same file is modified in the official repository, you may find that a conflict is created when you do <tt>git merge origin/master</tt>.

To resolve this, you will need to find the conflicts (the attempt to merge will tell you where they are) and resolve them. The [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html|<tt>git merge</tt> man page] has more information on the presentation and resolution of conflicts.

After the conflict is resolved, you'll need to commit the resolved files.
git commit -a

Maintaining Moodle customisations with Git

2011-03-15T09:32:35Z

Marxjohnson:

'''This page is a work in progress'''

Git makes it very easy to maintain local customisations to Moodle alongside updates from the official Moodle repository.
This page assumes you installed Moodle following [[Installing Moodle from Git repository]]. It also assumes you understand basic version control principles (repositories, branches, conflicts) and have a basic working knowledge of Git.

From your moodle directory, create a new branch for developing your customisation, and move to that branch:
git checkout -b myfeature

Switched to a new branch 'myfeature'
This will give you a seperate copy of the Moodle code to work on without affecting the master branch. It's not recommended that you do this on your production server, as it will cause the code to be available immediately as it's saved.

Do your customisations, add any new files to git, and commit the changes
git add .
git status
git commit -m "Description of the change"

''Ouch! this next bit is a really bad idea. I don't know what you are trying to achieve, but this is not the right way to do it!!!--[[User:Tim Hunt|Tim Hunt]] 09:09, 15 March 2011 (UTC)''

''Please edit it to the right way to do it then :-)[[User:Mark Johnson|Mark Johnson]]''

Switch back to the master branch and merge the changes
git checkout master
git merge myfeature
Any future development can take place on the myfeature branch, and be merged into master in this way

Even after local modifications have been made, you can pull in updates from the official git repository
git checkout master
git fetch
git merge origin/master

=== Conflicts ===
If you create a local modification to a file, and that same file is modified in the official repository, you may find that a conflict is created when you do <tt>git merge origin/master</tt>.

To resolve this, you will need to find the conflicts (the attempt to merge will tell you where they are) and resolve them. The [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html|<tt>git merge</tt> man page] has more information on the presentation and resolution of conflicts.

After the conflict is resolved, you'll need to commit the resolved files.
git commit -a

Maintaining Moodle customisations with Git

2011-03-15T09:30:52Z

Marxjohnson:

'''This page is a work in progress'''

Git makes it very easy to maintain local customisations to Moodle alongside updates from the official Moodle repository.
This page assumes you installed Moodle following [[Installing Moodle from Git repository]]. It also assumes you understand basic version control principles (repositories, branches, conflicts) and have a basic working knowledge of Git.

From your moodle directory, create a new branch for developing your customisation, and move to that branch:
git checkout -b myfeature

Switched to a new branch 'myfeature'
This will give you a seperate copy of the Moodle code to work on without affecting the master branch. It's not recommended that you do this on your production server, as it will cause the code to be available immediately as it's saved.

Do your customisations, add any new files to git, and commit the changes
git add .
git status
git commit -m "Description of the change"

''Ouch! this next bit is a really bad idea. I don't know what you are trying to achieve, but this is not the right way to do it!!!--[[User:Tim Hunt|Tim Hunt]] 09:09, 15 March 2011 (UTC)''

Switch back to the master branch and merge the changes
git checkout master
git merge myfeature
Any future development can take place on the myfeature branch, and be merged into master in this way

Even after local modifications have been made, you can pull in updates from the official git repository
git checkout master
git fetch
git merge origin/master

=== Conflicts ===
If you create a local modification to a file, and that same file is modified in the official repository, you may find that a conflict is created when you do <tt>git merge origin/master</tt>.

To resolve this, you will need to find the conflicts (the attempt to merge will tell you where they are) and resolve them. The [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html|<tt>git merge</tt> man page] has more information on the presentation and resolution of conflicts.

After the conflict is resolved, you'll need to commit the resolved files.
git commit -a

Installing Moodle from Git repository

2011-03-15T09:30:30Z

Marxjohnson: Added caveats to the top of the page

'''This page is a work in progress'''
== Linux/Unix command line ==
These instructions should be very similar on Windows.

Move to the directory where you wish to install Moodle. Moodle will go in ./moodle, relative to this directory
cd ~
Clone the offical Moodle repository via git
git clone git://git.moodle.org/moodle.git
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 https://github.com/moodle/moodle.git

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 (you can rename this if you wish)
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 version is now 2 simple commands:
git fetch
git merge origin/master

Git repositories for contrib modules

2011-03-15T09:29:57Z

Marxjohnson: Added caveats to the top of the page

'''This page is a work in progress.''' The instructions here assume that you have a working knowledge of git.

Managing contrib plugin with git makes it easy to make local modifications and pull in updates.
There are several options for managing a contrib plugin with git:
# Add the module to your main moodle git repository
# Create a self-contained repository for the plugin in a subdirectory
# Create a git submodule, which creates a repository for the plugin but tracks updates in the main repository too. It also allows you to clone the plugins with the main repository
Having used all of the above, the method I'd recommend is number 2, as it's most convenient. The main disadvantage of 1 is that you can't easily pull in updates, and the main disadvantage of 3 is that you have to make each commit to the module twice.

== Creating a new plugin ==
If you intend to publish the plugin, I highly recommend creating a [http://github.org github] repository from the start. This will allow you to publish with a single command when you're ready. Just go to the site, sign up for an account, create a new repository. The naming convention for Moodle plugin repositories is <tt>moodle-plugintype_pluginname</tt>.

Github will give you instructions for cloning your (blank) repository. If you're using option 2 above, navigate to the directory for the plugin type you're developing (e.g. /block, /mod, /local) and run the <tt>git clone</tt> command there. This will create a subdirectory called <tt>moodle-plugintype_pluginname</tt>, rename this to <tt>pluginname</tt> and you're good to go. <tt>cd</tt> into this directory to perform git commands on this plugin's repository - outside of this directory will perform them on the main Moodle repository.

You can then develop and test your changes locally, and when you're ready to publish, run
git push origin

== Installing a third-party plugin ==
Installing a plugin developed by a third party differs depending on whether they have used git or not.
If they have used git, you can follow the instructions above, but skip out the part where you create a new repository and clone their own git repository instead.

If they haven't used git, you can still use git (and even github, if you like) to track local modifications to the plugin. Simply create a directory for the plugin
mkdir ~/moodle/blocks/newblock
Initialise a new git repository there
cd ~/moodle/blocks/newblock
git init
unzip or copy the files to the repository
cd ~
tar -xf newblock.tar.gz
cp newblock/* ~/moodle/blocks/newblock
add and commit the files
cd ~/moodle/blocks/newblock
git add .
git commit . -m "Added files for newblock"
When installing updates, you'll need to copy the new files in place of the old one, and re run the <tt>git add</tt> and <tt>git commit</tt> commands.

== Moving a plugin to it's own repository ==
You may have developed a plugin within your main Moodle repository, but want to move it to a separate one to make it easier to publish. Using <tt>git filter-branch</tt>, we can achieve this and maintain all existing history for the plugin's files.

First, you'll need a fresh copy of moodle (this will become your new moodle repository)
mkdir ~/newmoodle
cd ~/newmoodle
git clone git://git.moodle.org/moodle.git
This will create a clone of Moodle without your plugins in ~/newmoodle/moodle
Next, you need to clone your local Moodle repository (why will become clear).
mkdir ~/moodleclone
cd ~/moodleclone
git clone ~/moodle
This will create a clone of your current moodle development repository, with your plugins, in ~/moodleclone/moodle
Now, we'll use the <tt>git filter-branch</tt> command to reduce this clone to just the plugin.
cd ~/moodleclone/moodle
git filter-branch --subdirectory-filter blocks/myblock/
The files from blocks/myblock/ will now be at the root of the repository. All other files will have been removed (this is why we're using a clone).
You can now track the plugin in it's own repository by cloning this reduced repository to a subdirectory of the new moodle clone.
cd ~/newmoodle/blocks
git clone ~/moodleclone/moodle myblock
This will clone the block's files, with the full history, into their own repository in the myblock subdirectory.
You can now delete ~/moodleclone/moodle, and repeat with any other plugins you've developed.

Git repositories for contrib modules

2011-03-15T09:28:46Z

Marxjohnson: Created initial page

Managing contrib plugin with git makes it easy to make local modifications and pull in updates.
There are several options for managing a contrib plugin with git:
# Add the module to your main moodle git repository
# Create a self-contained repository for the plugin in a subdirectory
# Create a git submodule, which creates a repository for the plugin but tracks updates in the main repository too. It also allows you to clone the plugins with the main repository
Having used all of the above, the method I'd recommend is number 2, as it's most convenient. The main disadvantage of 1 is that you can't easily pull in updates, and the main disadvantage of 3 is that you have to make each commit to the module twice.

== Creating a new plugin ==
If you intend to publish the plugin, I highly recommend creating a [http://github.org github] repository from the start. This will allow you to publish with a single command when you're ready. Just go to the site, sign up for an account, create a new repository. The naming convention for Moodle plugin repositories is <tt>moodle-plugintype_pluginname</tt>.

Github will give you instructions for cloning your (blank) repository. If you're using option 2 above, navigate to the directory for the plugin type you're developing (e.g. /block, /mod, /local) and run the <tt>git clone</tt> command there. This will create a subdirectory called <tt>moodle-plugintype_pluginname</tt>, rename this to <tt>pluginname</tt> and you're good to go. <tt>cd</tt> into this directory to perform git commands on this plugin's repository - outside of this directory will perform them on the main Moodle repository.

You can then develop and test your changes locally, and when you're ready to publish, run
git push origin

== Installing a third-party plugin ==
Installing a plugin developed by a third party differs depending on whether they have used git or not.
If they have used git, you can follow the instructions above, but skip out the part where you create a new repository and clone their own git repository instead.

If they haven't used git, you can still use git (and even github, if you like) to track local modifications to the plugin. Simply create a directory for the plugin
mkdir ~/moodle/blocks/newblock
Initialise a new git repository there
cd ~/moodle/blocks/newblock
git init
unzip or copy the files to the repository
cd ~
tar -xf newblock.tar.gz
cp newblock/* ~/moodle/blocks/newblock
add and commit the files
cd ~/moodle/blocks/newblock
git add .
git commit . -m "Added files for newblock"
When installing updates, you'll need to copy the new files in place of the old one, and re run the <tt>git add</tt> and <tt>git commit</tt> commands.

== Moving a plugin to it's own repository ==
You may have developed a plugin within your main Moodle repository, but want to move it to a separate one to make it easier to publish. Using <tt>git filter-branch</tt>, we can achieve this and maintain all existing history for the plugin's files.

First, you'll need a fresh copy of moodle (this will become your new moodle repository)
mkdir ~/newmoodle
cd ~/newmoodle
git clone git://git.moodle.org/moodle.git
This will create a clone of Moodle without your plugins in ~/newmoodle/moodle
Next, you need to clone your local Moodle repository (why will become clear).
mkdir ~/moodleclone
cd ~/moodleclone
git clone ~/moodle
This will create a clone of your current moodle development repository, with your plugins, in ~/moodleclone/moodle
Now, we'll use the <tt>git filter-branch</tt> command to reduce this clone to just the plugin.
cd ~/moodleclone/moodle
git filter-branch --subdirectory-filter blocks/myblock/
The files from blocks/myblock/ will now be at the root of the repository. All other files will have been removed (this is why we're using a clone).
You can now track the plugin in it's own repository by cloning this reduced repository to a subdirectory of the new moodle clone.
cd ~/newmoodle/blocks
git clone ~/moodleclone/moodle myblock
This will clone the block's files, with the full history, into their own repository in the myblock subdirectory.
You can now delete ~/moodleclone/moodle, and repeat with any other plugins you've developed.

Maintaining Moodle customisations with Git

2011-03-15T08:56:07Z

Marxjohnson: New page: Git makes it very easy to maintain local customisations to Moodle alongside updates from the official Moodle repository. This page assumes you installed Moodle following [[Installing Moodl...

Git makes it very easy to maintain local customisations to Moodle alongside updates from the official Moodle repository.
This page assumes you installed Moodle following [[Installing Moodle from Git repository]]. It also assumes you understand basic version control principles (repositories, branches, conflicts) and have a basic working knowledge of Git.

From your moodle directory, create a new branch for developing your customisation, and move to that branch:
git branch myfeature
git checkout myfeature

Switched to branch 'myfeature'
This will give you a seperate copy of the Moodle code to work on without affecting the master branch. It's not recommended that you do this on your production server, as it will cause the code to be available immediately as it's saved.

Do your customisations, add any new files to git, and commit the changes
git add .
git commit . -m "Description of the change"

Switch back to the master branch and merge the changes
git checkout master
git merge myfeature
Any future development can take place on the myfeature branch, and be merged into master in this way

Even after local modifications have been made, you can pull in updates from the official git repository
git checkout master
git fetch
git merge origin/master

=== Conflicts ===
If you create a local modification to a file, and that same file is modified in the official repository, you may find that a conflict is created when you do <tt>git merge origin/master</tt>.

To resolve this, you will need to find the conflicts (the attempt to merge will tell you where they are) and resolve them. The [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html|<tt>git merge</tt> man page] has more information on the presentation and resolution of conflicts.

After the conflict is resolved, you'll need to commit the resolved files.
git commit -a

Installing Moodle from Git repository

2011-03-15T08:42:26Z

Marxjohnson: /* Linux/Unix command line */

== Linux/Unix command line ==
These instructions should be very similar on Windows.

Move to the directory where you wish to install Moodle. Moodle will go in ./moodle, relative to this directory
cd ~
Clone the offical Moodle repository via git
git clone git://git.moodle.org/moodle.git
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 https://github.com/moodle/moodle.git

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 (you can rename this if you wish)
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 version is now 2 simple commands:
git fetch
git merge origin/master

Installing Moodle from Git repository

2011-03-15T08:40:56Z

Marxjohnson: Initial draft of instructions

Git

2011-03-15T08:28:06Z

Marxjohnson: /* Moodle specific guides */

[http://git-scm.com/ Git] is a free and open source version control system. Git is a more sophisticated replacement for [[CVS]]. You can find the official Git Moodle repository at http://git.moodle.org/ or mirror at https://github.com/moodle/moodle. The particular advantage of Git is its distributed model, making it ideal for managing local customisations to Moodle. It is also suitable for development of contrib plugins for Moodle.

Use the ''Git'' category link at the end of this page to get a list of all Git related pages.

==Books and tutorials==
* [http://progit.org/ Pro Git Book]
* [http://book.git-scm.com/ Git Community Book]
* [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html Official Git tutorial]
* [http://help.github.com/ GitHub Help]

==Moodle specific guides==
* [[Installing Moodle from Git repository]] - WIP
* [[Maintaining Moodle customisations with Git]] - WIP
* Submitting patches and pull requests - TODO
* [[Git repositories for contrib modules]] - WIP

==Tools==
The most powerful tool you can git is probably command line git. If you prefer clicking you can try one of the following, more information at [http://git-scm.com/tools http://git-scm.com/tools].

'''IDE integrations'''
* [http://www.eclipse.org/egit/ EGit plugin for Eclipse IDE]
* [http://netbeans.org/projects/versioncontrol/pages/Git_main Netbeans] - early access official Git plugin for Netbeans
* [http://www.jetbrains.com/phpstorm/ PHPStorm] - commercial IDE with Git support

'''Frontends'''
* [http://code.google.com/p/tortoisegit/ TortoiseGit] - Windows only UI
* [http://gitx.frim.nl/ GitX] - OS X only UI
* [http://www.syntevo.com/smartgit/index.html SmartGit] - feature rich multiplatform UI (free for non-commercial use)

==Hosting==
* [http://github GitHub] - probably the best hosting choice for beginners
* [http://gitorious.org/ Gitorious] - free hosting running on open source code

==See also==

* [[Development:Git Migration]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=162723 Moving from CVS to git in November 2010] forum discussion

[[Category:Git]]
[[Category:Administrator]]

Javascript FAQ

2011-02-08T14:37:40Z

Marxjohnson:

== What is JavaScript? ==

JavaScript is a scripting language widely used for client-side web development.

== Where do I find general information about JavaScript? ==

=== Online resources: ===
* [http://en.wikipedia.org/wiki/JavaScript JavaScript (Wikipedia)]
* [http://www.w3schools.com/JS/ JavaScript Tutorial] at W3Schools.com
* [http://articles.sitepoint.com/category/javascript Sitepoint JavaScript tutorials]

=== Books: ===
* [http://oreilly.com/catalog/9780596101992 JavaScript: The Definitive Guide, Fifth Edition] by David Flanagan - Really the ultimate reference guide (nearly 1000 pages).
* [http://www.sitepoint.com/books/jsant1/ The JavaScript Anthology: 101 Essential Tips, Tricks & Hacks] by James Edwards & Cameron Adams - Promotes accessible JavaScript solutions by following the principles of [[Development:Progressive enhancement| progressive enhancement]] and [[Development:Unobtrusive_Javascript| unobtrusive scripting]].

== How is JavaScript used by Moodle? ==

* See [https://docs.moodle.org/en/Category:Javascript Category:Javascript].

== Where do I find more information about JavaScript in Moodle? ==

* [[Development:JavaScript_guidelines|JavaScript Guidelines]] by Tim Hunt (work in progress)
* [http://moodle.org/mod/forum/discuss.php?d=106312 Use of JavaScript in Moodle] discussion in the General developer forum

== What JavaScript library does Moodle use? ==

=== Yahoo! User Interface Library (YUI) ===
Moodle uses the Yahoo! User Interface Library (YUI).

==== Online resources: ====
* [http://developer.yahoo.com/yui/ Yahoo! User Interface Library (YUI)]
* [[Development:YUI]] in the Moodle documentation

==== Books: ====
* [http://www.packtpub.com/yahoo!-user-interface-library-yui/book Learning the Yahoo! User Interface Library] by Dan Wellman

==== How/Why was YUI chosen for Moodle? ====

The decision was made in [http://moodle.org/mod/forum/discuss.php?d=48478 this thread in the General Developer Forum].

==== yui_module function in Moodle 2.0 ====
See [http://moodle.org/mod/forum/discuss.php?d=154359 JavaScript Cache and YUI Modules] and MDL-22920.

== What other JavaScript libraries are around? ==

* A nice comparison chart: [http://wiki.freaks-unidos.net/javascript-libraries Evaluation of JavaScript Libraries]

=== jQuery ===

jQuery is another popular JavaScript library, used among others by Drupal, Joomla and WordPress.

==== Online resources: ====
* [http://jquery.com/ jQuery]
* [http://visualjquery.com Visual jQuery]
* [http://jqueryfordesigners.com jQuery for Designers]

==== Books: ====
* [http://www.manning.com/bibeault/ jQuery in Action] by Bear Bibeault and Yehuda Katz
* [http://www.packtpub.com/jQuery/book Learning jQuery] by Karl Swedberg and Jonathan Chaffer
* [http://www.packtpub.com/jquery-reference-guide-Open-Source/book jQuery Reference Guide] by Jonathan Chaffer and Karl Swedberg

== What does AJAX mean? ==
AJAX means "Asynchronous JavaScript and XML". It is a group of interrelated web development techniques used to create interactive web applications or rich Internet applications.

See [http://en.wikipedia.org/wiki/Ajax_(programming) AJAX (Wikipedia)] for general information and [[AJAX]] for information on AJAX and Moodle.

== See also ==

* [[User:Frank_Ralf/JavaScript1]] compares different solutions (plain JavaScript, YUI, and jQuery) to a simple enhancement to a form.
* [[Development:Using jQuery with Moodle 2.0]]
* [[Javascript and YUI 3 FAQ]]

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

Development:How to create a YUI 3 module

2011-02-08T14:01:10Z

Marxjohnson: /* What else to read */

{{Moodle 2.0}}This document explains how to create a YUI 3 module in Moodle.

= The two ways to write a YUI 3 module =
There is two ways to write a YUI 3 module. The two following paragraphs are sourced from a chat with Sam Hemelryk.
==The static module==
The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature.
If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

==The YUI3 Moodle Module==
This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a '''yui''' directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named.
Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g.'''/local/myplugin/yui/mymodule/mymodule.js'''
The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

= Static module quick start =
1. Create a module.js file somewhere

2. The two ways Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)
<code php>
//example:
case 'core_rating':
$module = array('name' => 'core_rating',
'fullpath' => '/rating/module.js',
'requires' => array('node', 'event', 'overlay', 'io', 'json'));
</code>
b- the file is in a local plugin: the first line of your module should be
<code javascript>
M.local_xxx = {
</code>
xxx being your plugin directory name.

3. Write the module.js
<code javascript>
M.local_hub={
Y : null,
transaction : [],
init : function(Y){
alert('hub module initialisation');
this.Y = Y;
},
}
</code>
4. Call this module. It can not be in a php renderer script. However you could call it where you call the renderer.
<code php>
$PAGE->requires->js_init_call('M.local_hub.init');
You should now have loaded and called your first YUI 3 module in Moodle.
</code>
5. If you want to load your module with some other YUI modules
<code php>
$jsmodule = array(
'name' => 'local_hub',
'fullpath' => '/local/hub/module.js',
'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
$PAGE->requires->js_init_call('M.local_hub.init',
null, false, $jsmodule);
</code>
6. If you want to pass parameter to the init function

PHP:
<code php>
$PAGE->requires->js_init_call('M.local_hub.init',
array('this is the param1 value'), false, $jsmodule);
</code>
JS:
<code javascript>
init : function(Y, params){
alert(params);
....
}
</code>
7. Then you should be able to fill the module with your own YUI javascript from [http://developer.yahoo.com/yui/3/examples/ YUI examples].

= YUI 3 Moodle Module quick start =
1. Create the module_name.js file in /local/pluginname/yui/module_name/modulename.js or in /mod/modname/yui/modulename/modulename.js

2. The basic module_name.js structure is:
<code javascript>
YUI.add('moodle-local_pluginname-modulename', function(Y) {
var ModulenameNAME = 'this_is_a_module_name';
var MODULENAME = function() {
MODULENAME.superclass.constructor.apply(this, arguments);
}
Y.extend(MODULENAME, Y.Base, {
initializer : function(config) { //'config' contains the parameter values
alert('I am in initializer');
}
}, {
NAME : ModulenameNAME, //module name is something mandatory.
//It should be in lower case without space
//as YUI use it for name space sometimes.
ATTRS : {
aparam : {}
} // Attributs are the parameters sent when the $PAGE->requires->yui_module calls the module.
// Here you can declare default values or run functions on the parameter.
// The param names must be the same as the ones declared
// in the $PAGE->requires->yui_module call.
});
M.local_pluginname = M.local_pluginname || {}; //this line use existing name path if it exists, ortherwise create a new one.
//This is to avoid to overwrite previously loaded module with same name.
M.local_pluginname.init_modulename = function(config) { //'config' contains the parameter values
alert('I am in the javascript module, Yeah!');
return new MODULENAME(config); //'config' contains the parameter values
}
}, '@VERSION@', {
requires:['base','another_required_YUI_module', 'a_moodle_YUI_module']
});
</code>
3. Call the javascript in PHP (if you copied the previous javascript, 2 javascript alert should appear.)
<code php>
$PAGE->requires->yui_module('moodle-local_pluginname-modulename', 'M.local_pluginname.init_modulename',
array(array('aparam'=>'paramvalue')));
</code>
== Full simple example==
Once you understand and run the above quick start, here is simple YUI 3 example. It shows how to use another YUI 3 module in your module, and to use some events.
=== It includes===
* display a parameter value in two javascript alert boxes => demonstrate how to pass a param to the initialize function in two different ways
* display an overlay when you click on an image
* hide the overlay when you click on the body
* some commented code to see how Moodle YUI exception works

=== PHP ===
Create a [https://docs.moodle.org/en/Development:Local_customisation basic local plugin] (in this example it is named hub) in /local/hub/ and add this code into one of the plugin pages:
<code php>
$PAGE->requires->yui_module('moodle-local_hub-comments', 'M.local_hub.init_comments',
array(array('commentids' => '1 , 23 ,45')));
</code>

=== HTML ===
The plugin page should generate this HTML code:
<code xml>

<div id="comments"><img src='http://moodle.org/theme/moodle2/pix/moodle-logo.gif' alt='the image to click on'/></div>


<div id="commentoverlay" class="yui3-overlay-loading">
<div class="yui3-widget-hd">Comment</div>
<div class="yui3-widget-bd">this is a comment</div>
<div class="yui3-widget-bd">this is another comment</div>
</div>
</code>

=== CSS ===
The plugin style.css should contain:
<code css>
/* Hide overlay markup while loading, if js is enabled */
.yui3-js-enabled .yui3-overlay-loading {
top:-1000em;
left:-1000em;
position:absolute;
}

/* Overlay Look/Feel */
.yui3-overlay-content {
padding:3px;
border:1px solid #000;
background-color:#aaa;
}

.yui3-overlay-content .yui3-widget-hd {
padding:5px;
border:2px solid #aa0000;
background-color:#fff;
}

.yui3-overlay-content .yui3-widget-bd {
padding:5px;
border:2px solid #0000aa;
background-color:#fff;
}
</code>

=== JS ===
In /local/hub/yui/comments/comments.js
<code javascript>
YUI.add('moodle-local_hub-comments', function(Y) {

var COMMENTSNAME = 'hub_comments';

//we declare the overlay here so it's accessible to all the extended class function'
var overlay = new Y.Overlay({
srcNode:"#commentoverlay", //the main div with id = commentoverlay
width:"10em",
height:"10em",
xy:[ 0, 0],
visible: false //by default it is not displayed
});

var COMMENTS = function() {
COMMENTS.superclass.constructor.apply(this, arguments);
}

Y.extend(COMMENTS, Y.Base, {

event:null,

initializer : function(params) {

//Example how to retrieve the parameter,
//see what happens if you don't pass the parameter in the call
alert(this.get('commentids')); // You usually use an attribute because
//a attribut can have default value.
//use the ATTRS default value if not passed as parameter
alert(params.commentids); // undefined if not passed as parameter

//render the overlay
overlay.render();

// position the overlay in the middle of the web browser window
var WidgetPositionAlign = Y.WidgetPositionAlign;
overlay.set("align", {
node:"", //empty => viewport
points:[WidgetPositionAlign.CC, WidgetPositionAlign.CC]
});

//attach a show event on the div with id = comments
//we also change the div style to display the click zone
Y.one('#comments').setStyle("border", "1px solid red").on('click', this.show, this);

//uncomment the try content to see how works exception in Moodle
//this exception has been specially created for Moodle
try {
//surely_not_existing_js_function();
} catch (exception) {
new M.core.exception(exception);
}

},

show : function (e) {
overlay.show(); //show the overlay

e.halt(); // we are going to attach a new 'hide overlay' event to the body,
// because javascript always propagate event to parent tag,
// we need to tell Yahoo to stop to call the event on parent tag
// otherwise the hide event will be call right away.

//we add a new event on the body in order to hide the overlay for the next click
this.event = Y.one(document.body).on('click',this.hide,this);
},

hide : function () {
overlay.hide(); //hide the overlay
this.event.detach(); //we need to detach the hide event
//Note: it would work without but create js warning everytime
//we click on the body
}

}, {
NAME : COMMENTSNAME,
ATTRS : {
commentids: {value : 450} //default value (has no purpose in this code except to show you
// how to pass/use a param value)
}
});

M.local_hub = M.local_hub || {};
M.local_hub.init_comments = function(params) {
return new COMMENTS(params);
}

}, '@VERSION@', {
requires:['base','overlay', 'moodle-enrol-notification']
//Note: 'moodle-enrol-notification' contains Moodle YUI exception
});
</code>

= What else to read =
Two pages are important to start with when you discover YUI 3
* you should read the [http://developer.yahoo.com/yui/3/base/ base YUI doc]. It is very useful to understand the YUI 3 Moodle module.
* you want to have a look to the [http://developer.yahoo.com/yui/3/examples/ YUI 3 examples]. Always open the examples in a window to have a look to the complete example codes.

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

== See Also ==
[[Javascript and YUI 3 FAQ]]

Javascript FAQ

2011-02-08T14:00:42Z

Marxjohnson: /* See also */

== What is JavaScript? ==

JavaScript is a scripting language widely used for client-side web development.

== Where do I find general information about JavaScript? ==

=== Online resources: ===
* [http://en.wikipedia.org/wiki/JavaScript JavaScript (Wikipedia)]
* [http://www.w3schools.com/JS/ JavaScript Tutorial] at W3Schools.com
* [http://articles.sitepoint.com/category/javascript Sitepoint JavaScript tutorials]

=== Books: ===
* [http://oreilly.com/catalog/9780596101992 JavaScript: The Definitive Guide, Fifth Edition] by David Flanagan - Really the ultimate reference guide (nearly 1000 pages).
* [http://www.sitepoint.com/books/jsant1/ The JavaScript Anthology: 101 Essential Tips, Tricks & Hacks] by James Edwards & Cameron Adams - Promotes accessible JavaScript solutions by following the principles of [[Development:Progressive enhancement| progressive enhancement]] and [[Development:Unobtrusive_Javascript| unobtrusive scripting]].

== How is JavaScript used by Moodle? ==

* See [https://docs.moodle.org/en/Category:Javascript Category:Javascript].

== Where do I find more information about JavaScript in Moodle? ==

* [[Development:JavaScript_guidelines|JavaScript Guidelines]] by Tim Hunt (work in progress)
* [http://moodle.org/mod/forum/discuss.php?d=106312 Use of JavaScript in Moodle] discussion in the General developer forum

== What JavaScript library does Moodle use? ==

=== Yahoo! User Interface Library (YUI) ===
Moodle uses the Yahoo! User Interface Library (YUI).

==== Online resources: ====
* [http://developer.yahoo.com/yui/ Yahoo! User Interface Library (YUI)]
* [[Development:YUI]] in the Moodle documentation

==== Books: ====
* [http://www.packtpub.com/yahoo!-user-interface-library-yui/book Learning the Yahoo! User Interface Library] by Dan Wellman

==== How/Why was YUI chosen for Moodle? ====

The decision was made in [http://moodle.org/mod/forum/discuss.php?d=48478 this thread in the General Developer Forum].

==== yui_module function in Moodle 2.0 ====
See [http://moodle.org/mod/forum/discuss.php?d=154359 JavaScript Cache and YUI Modules] and MDL-22920.

== What other JavaScript libraries are around? ==

* A nice comparison chart: [http://wiki.freaks-unidos.net/javascript-libraries Evaluation of JavaScript Libraries]

=== jQuery ===

jQuery is another popular JavaScript library, used among others by Drupal, Joomla and WordPress.

==== Online resources: ====
* [http://jquery.com/ jQuery]
* [http://visualjquery.com Visual jQuery]
* [http://jqueryfordesigners.com jQuery for Designers]

==== Books: ====
* [http://www.manning.com/bibeault/ jQuery in Action] by Bear Bibeault and Yehuda Katz
* [http://www.packtpub.com/jQuery/book Learning jQuery] by Karl Swedberg and Jonathan Chaffer
* [http://www.packtpub.com/jquery-reference-guide-Open-Source/book jQuery Reference Guide] by Jonathan Chaffer and Karl Swedberg

== What does AJAX mean? ==
AJAX means "Asynchronous JavaScript and XML". It is a group of interrelated web development techniques used to create interactive web applications or rich Internet applications.

See [http://en.wikipedia.org/wiki/Ajax_(programming) AJAX (Wikipedia)] for general information and [[AJAX]] for information on AJAX and Moodle.

== See also ==

* [[User:Frank_Ralf/JavaScript1]] compares different solutions (plain JavaScript, YUI, and jQuery) to a simple enhancement to a form.
* [[Development:Using jQuery with Moodle 2.0]]

[[Category:FAQ]]
[[Category:Javascript]]
[[Javascript and YUI 3 FAQ]]
[[Category:AJAX]]

Development:JavaScript guidelines

2011-02-08T14:00:13Z

Marxjohnson: /* See also */

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals.

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.
Strings that are passed to Javascript in this way are then available from Javascript using M.util.get_string(), which works just like the PHP function.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Javascript and YUI 3 FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Development:JavaScript guidelines

2011-02-08T13:52:29Z

Marxjohnson: /* How to achive these general principles in Moodle */

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals.

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.
Strings that are passed to Javascript in this way are then available from Javascript using M.util.get_string(), which works just like the PHP function.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Message My Teacher Block

2011-01-18T14:54:36Z

Marxjohnson: New page: Message My Teacher is a very simple block. It will display a list users who are teachers for the current course with links to send them a message. == Configuration == The block requires t...

Message My Teacher is a very simple block. It will display a list users who are teachers for the current course with links to send them a message.

== Configuration ==
The block requires that you select the roles you wish to consider "teachers" (those who will appear in the block). In Site Administration/Plugins/Blocks/Message My Teacher you can select as many roles as necessary by checking the appropriate boxes.

== Usage ==
Anyone visiting a page with the block on will see a list of all users with the selected roles. Clicking the user's name will take them to a screen allowing them to compose a message to that user. '''Note:''' users will never see their own name on this list, as they will never need to message themselves. If they are assigned the appropriate role, they will still appear to other users.

[[Category:Block]]

Metacourse Link Block

2011-01-18T14:49:05Z

Marxjohnson: New page: This block allows Metacourse/Child course links to be created/kept up to date via CSV files. It is very similar in both appearance and programming to the Tutor Link Block. It can be o...

This block allows Metacourse/Child course links to be created/kept up to date via CSV files. It is very similar in both appearance and programming to the [[Tutor Link Block]].

It can be operated in two modes:

Manual Upload - any user with the block/metalink:use capability (by default, only admins) can upload a file to process on demand.

Automatic - a file location is configured, then the block automatically checks this location. If a file is found, it is processed and results emailed to the administrator.

== Configuration ==

The block has several configuration options, found in Site Administration/Plugins/Blocks/Upload Tutor Relationships.
*''Location of File for Automatic Processing'' is the location of the file on the server's local file system to be processed by the block's cron job, allowing periodic updates of role assignments. Leaving this blank will disable the cron job.
*''Keep processed files'' allows files processed by cron jobs to be kept for future reference.
*''Processed file location'' is the folder that processed files will be placed in, if ''Keep processed files'' is ticked.
*''Days to keep processed files for'' is self-explanatory. After this many days, processed files will be deleted.

== Usage ==

=== Correct File Format ===
The files to be processed should be in CSV format (hopefully no surprises there).

{{Moodle 1.9}}
They may consist of any number of rows, each with three fields: tutor idnumber,tutee idnumber, action; it is important to note that the idnumbers are expected to be populated from an external database, they are not the id field in the user table. Action can be add or del, with add creating relationships and del deleting relationships. None of the fields should be delimited.

{{Moodle 2.0}}
As of Moodle 2.0, the order of the fields changed slightly to make them more consistent with the Flatfile Enrolements plugin.
The format for each row is now: action, parent course idnumber, child course idnumber. For example, a file with this contents:
add, 1234, 4321
add, 1234, 4322
del, 2232, 3223
Will assign the courses with idnumbers 4321 and 4321 as children of the course with idnumber 1234, then remove the course with idnumber 3223 from the course with idnumber 2232.
Note than unlike 1.9, each row '''must''' contain three columns.

Trying to add relationships that already exist in Moodle or remove those that dont will not cause problems, as this block will skip over those records.

=== Manual upload ===
After the CSV file is created, navigate to the page containing the block, and upload the file. It will be processed and a report will appear showing you the operations that were successful, along with any errors.

=== Automatic processing ===
A file placed at the path specified in ''Location of file for automatic processing'' will be processed automatically when the block's cron job runs. A report will then be emailed to the Moodle Administrator.

[[Category:Block]]

Tutor Link Block

2011-01-18T14:44:54Z

Marxjohnson:

This block allows user relationships (that is one user assigned a role in another user's context) to be created/kept up to date via CSV files. It was written for personal tutors, but would work equally well for parents.

It can be operated in two modes:

Manual Upload - any user with the block/tutorlink:use capability (by default, only admins) can upload a file to process on demand.

Automatic - a file location is configured, then the block automatically checks this location. If a file is found, it is processed and results emailed to the administrator.

== Configuration ==

The block has several configuration options, found in Site Administration/Plugins/Blocks/Upload Tutor Relationships.
*''Tutor Role'' is the role that will be assigned by the block. As of 2.0, a role must be allowed to be assigned at the User context level before it can be selected here. This is configured on the role's ''Define Role'' page.
*''Location of File for Automatic Processing'' is the location of the file on the server's local file system to be processed by the block's cron job, allowing periodic updates of role assignments. Leaving this blank will disable the cron job.
*''Keep processed files'' allows files processed by cron jobs to be kept for future reference.
*''Processed file location'' is the folder that processed files will be placed in, if ''Keep processed files'' is ticked.
*''Days to keep processed files for'' is self-explanatory. After this many days, processed files will be deleted.

== Usage ==

=== Correct File Format ===
The files to be processed should be in CSV format (hopefully no surprises there).

{{Moodle 1.9}}
They may consist of any number of rows, each with three fields: tutor idnumber,tutee idnumber, action; it is important to note that the idnumbers are expected to be populated from an external database, they are not the id field in the user table. Action can be add or del, with add creating relationships and del deleting relationships. None of the fields should be delimited.

{{Moodle 2.0}}
As of Moodle 2.0, the order of the fields changed slightly to make them more consistent with the Flatfile Enrolements plugin.
The format for each row is now: action, tutor idnumber, tutee idnumber. For example, a file with this contents:
add, 1234, 4321
add, 1234, 4322
del, 2232, 3223
Will assign the user with the idnumber 1234 to users with idnumbers 4321 and 4321, then remove the user with idnumber 2232 from the user 3223.

Trying to add relationships that already exist in Moodle or remove those that dont will not cause problems, as this block will skip over those records.

=== Manual upload ===
After the CSV file is created, navigate to the page containing the block, and upload the file. It will be processed and a report will appear showing you the operations that were successful, along with any errors.

=== Automatic processing ===
A file placed at the path specified in ''Location of file for automatic processing'' will be processed automatically when the block's cron job runs. A report will then be emailed to the Moodle Administrator.

[[Category:Block]]

CSV user relationships block

2011-01-18T14:42:50Z

Marxjohnson: Redirecting to Tutor Link Block

#REDIRECT [[Tutor Link Block]]

CSV user relationships block

2011-01-18T14:42:26Z

Marxjohnson: Redirecting to Quick Find List Block

#REDIRECT [[Quick Find List Block]]

Tutor Link Block

2011-01-18T14:40:21Z

Marxjohnson: Copied from old CSV_user_relationships_block page and updated to include Moodle 2 specifics

This block allows user relationships (that is one user assigned a role in another user's context) to be created/kept up to date via CSV files. It was written for personal tutors, but would work equally well for parents.

It can be operated in two modes:

Manual Upload - any user with the block/tutorlink:use capability (by default, only admins) can upload a file to process on demand.

Automatic - a file location is configured, then the block automatically checks this location. If a file is found, it is processed and results emailed to the administrator.

== Configuration ==

The block has several configuration options, found in Site Administration/Plugins/Blocks/Upload Tutor Relationships.
*''Tutor Role'' is the role that will be assigned by the block. As of 2.0, a role must be allowed to be assigned at the User context level. This is configured on the role's ''Define Role'' page.
*''Location of File for Automatic Processing'' is the location of the file on the server's local file system to be processed by the block's cron job, allowing periodic updates of role assignments. Leaving this blank will disable the cron job.
*''Keep processed files'' allows files processed by cron jobs to be kept for future reference.
*''Processed file location'' is the folder that processed files will be placed in, if ''Keep processed files'' is ticked.
*''Days to keep processed files for'' is self-explanatory. After this many days, processed files will be deleted.

== Usage ==

=== Correct File Format ===
The files to be processed should be in CSV format (hopefully no surprises there).

{{Moodle 1.9}}
They may consist of any number of rows, each with three fields: tutor idnumber,tutee idnumber, action; it is important to note that the idnumbers are expected to be populated from an external database, they are not the id field in the user table. Action can be add or del, with add creating relationships and del deleting relationships. None of the fields should be delimited.

{{Moodle 2.0}}
As of Moodle 2.0, the order of the fields changed slightly to make them more consistent with the Flatfile Enrolements plugin.
The format for each row is now: action, tutor idnumber, tutee idnumber. For example, a file with this contents:
add, 1234, 4321
add, 1234, 4322
del, 2232, 3223
Will assign the user with the idnumber 1234 to users with idnumbers 4321 and 4321, then remove the user with idnumber 2232 from the user 3223.

Trying to add relationships that already exist in Moodle or remove those that dont will not cause problems, as this block will skip over those records.

=== Manual upload ===
After the CSV file is created, navigate to the page containing the block, and upload the file. It will be processed and a report will appear showing you the operations that were successful, along with any errors.

=== Automatic processing ===
A file placed at the path specified in ''Location of file for automatic processing'' will be processed automatically when the block's cron job runs. A report will then be emailed to the Moodle Administrator.

[[Category:Block]]

Accessibility Block

2011-01-18T14:15:21Z

Marxjohnson:

The Accessibility Block allows users to customise Moodle pages to meet their accessibility requirements.

== Configuration ==
{{Moodle 1.9}}
In Moodle 1.9, You will need to make a slight modification to any themes that your site uses to enable the block's customisations to be carried between pages. Simply open the <tt>header.html</tt> file of each theme, and add the following line before the <tt></head></tt> tag:
<nowiki></nowiki>
<link title="access_stylesheet"
rel="stylesheet"
href="<?php if($CFG->wwwroot != $CFG->httpswwwroot) {echo $CFG->httpswwwroot;} else {echo $CFG->wwwroot;} ?>
/blocks/accessibility/userstyles.php" type="text/css" />

{{Moodle 2.0}}
As of Moodle 2, the block requires no additional configuration to get per-user style modifications working. Since 2.0 the block includes [http://access.ecs.soton.ac.uk/ToolBar/ ATbar], which provides Text-To-Speech functionality (TTS). To get TTS working, you'll need to follow these instructions (currently only supported on Linux servers).
#Install the Accessibility block as normal
#Install Festival, the Text-To-Speech engine, on your server. This should install text2wave in /usr/bin. If not, you'll need to symlink it there.
#Install LAME, the MP3 utilities, on your server.
#Go to the Moodle root directory (at command line or in a file manager)
#From here, find blocks/accessibility/toolbar/server/TTS/SB_generateAudio.sh and make it executable. To do this from the terminal, run: <pre>chmod +x blocks/accessibility/toolbar/server/TTS/SB_generateAudio.sh</pre>
#Edit SB_generateAudio.sh to set the tmpdir variable at the top to a suitable temporary directory, and dirroot to the value of $CFG->dirroot in your Moodle config.php
#Change the ownership of blocks/accessibility/toolbar/server/TTS/cache to make it writable by the user the web server runs as. To do this on Ubuntu, run these commands: <pre>chown -R user:www-data blocks/accessibility/toolbar/server/TTS/cache</pre> <pre>chmod -R 775 blocks/accessibility/toolbar/server/TTS/cache</pre>
#Load a Moodle page containing the block, click "Launch ATbar", select some text, and click the Text-To-Speech button (speaker icon).

== Usage ==
The block's functionality is split into 2 areas: Native functions, and those functions provided bt ATbar.
=== Native Functions ===
There are 8 buttons on the block itself. The 3 buttons on the top row displaying an ''A'' control text size:
*Clicking [[Image:Accessibility_A-.png]] will decrease the text size.
*Clicking [[Image:Accessibility_A+.png]] will increase the text size.
*Clicking [[Image:Accessibility_A.png]] will reset the text size. If you had a saved setting for the text size, this will be cleared.

The final button on the top row saves styles changed by the block. Once you have altered the text size or colour scheme, the button will become active, shown by the blue arrow. When it's active, click [[Image:Accessibility_save.png]] to save settings. Once saved, they will persist between pages even when you log out.

The bottom row contains 4 buttons, each displaying a different colour scheme. Clicking any of these buttons [[Image:Accessibility_colours.png]] will apply that colour scheme to the page. Clicking the button on the far left will reset the scheme to default and clear any saved colour settings.

=== ATbar ===
{{Moodle 2.0}}
At the bottom of the block, you'll see a button labelled ''Launch ATbar'' and a checkbox labelled ''(always?)''<br />
[[Image:Accessibility_atbar.png]]<br />
Clicking the button will launch ATbar and hide the native controls. ATbar has several advanced Accessibility functions on top of the ability to change page styles, including Text-To-Speech and Dictionary lookup. Note that if you change styles with ATbar, they will '''not''' persist between pages as they do with the native functions, nor are you currently able to save them.
Ticking the checkbox will cause ATbar to be automatically loaded each time you visit a page containing the Accessibility block.
You can find out more about ATbar's functions by clicking the [[Image:Accessibility_help.png]] icon on the right of the bar itself.

[[Category:Block]]

Accessibility Block

2011-01-18T14:13:51Z

Marxjohnson: New page: The Accessibility Block allows users to customise Moodle pages to meet their accessibility requirements. == Configuration == {{Moodle 1.9}} In Moodle 1.9, You will need to make a slight m...

The Accessibility Block allows users to customise Moodle pages to meet their accessibility requirements.

== Configuration ==
{{Moodle 1.9}}
In Moodle 1.9, You will need to make a slight modification to any themes that your site uses to enable the block's customisations to be carried between pages. Simply open the <tt>header.html</tt> file of each theme, and add the following line before the <tt></head></tt> tag:
<nowiki></nowiki>
<link title="access_stylesheet"
rel="stylesheet"
href="<?php if($CFG->wwwroot != $CFG->httpswwwroot) {echo $CFG->httpswwwroot;} else {echo $CFG->wwwroot;} ?>
/blocks/accessibility/userstyles.php" type="text/css" />

{{Moodle 2.0}}
As of Moodle 2, the block requires no additional configuration to get per-user style modifications working. Since 2.0 the block includes [http://access.ecs.soton.ac.uk/ToolBar/ ATbar], which provides Text-To-Speech functionality (TTS). To get TTS working, you'll need to follow these instructions (currently only supported on Linux servers).
#Install the Accessibility block as normal
#Install Festival, the Text-To-Speech engine, on your server. This should install text2wave in /usr/bin. If not, you'll need to symlink it there.
#Install LAME, the MP3 utilities, on your server.
#Go to the Moodle root directory (at command line or in a file manager)
#From here, find blocks/accessibility/toolbar/server/TTS/SB_generateAudio.sh and make it executable. To do this from the terminal, run: <pre>chmod +x blocks/accessibility/toolbar/server/TTS/SB_generateAudio.sh</pre>
#Edit SB_generateAudio.sh to set the tmpdir variable at the top to a suitable temporary directory, and dirroot to the value of $CFG->dirroot in your Moodle config.php
#Change the ownership of blocks/accessibility/toolbar/server/TTS/cache to make it writable by the user the web server runs as. To do this on Ubuntu, run these commands: <pre>chown -R user:www-data blocks/accessibility/toolbar/server/TTS/cache</pre> <pre>chmod -R 775 blocks/accessibility/toolbar/server/TTS/cache</pre>
#Load a Moodle page containing the block, click "Launch ATbar", select some text, and click the Text-To-Speech button (speaker icon).

== Usage ==
The block's functionality is split into 2 areas: Native functions, and those functions provided bt ATbar.
=== Native Functions ===
There are 8 buttons on the block itself. The 3 buttons on the top row displaying an ''A'' control text size:
*Clicking [[Image:Accessibility_A-.png]] will decrease the text size.
*Clicking [[Image:Accessibility_A+.png]] will increase the text size.
*Clicking [[Image:Accessibility_A.png]] will reset the text size. If you had a saved setting for the text size, this will be cleared.

The final button on the top row saves styles changed by the block. Once you have altered the text size or colour scheme, the button will become active, shown by the blue arrow. When it's active, click [[Image:Accessibility_save.png]] to save settings. Once saved, they will persist between pages even when you log out.

The bottom row contains 4 buttons, each displaying a different colour scheme. Clicking any of these buttons [[Image:Accessibility_colours.png]] will apply that colour scheme to the page. Clicking the button on the far left will reset the scheme to default and clear any saved colour settings.

=== ATbar ===
{{Moodle 2.0}}
At the bottom of the block, you'll see a button labelled ''Launch ATbar'' and a checkbox labelled ''(always?)''\\
[[Image:Accessibility_atbar.png]]
Clicking the button will launch ATbar and hide the native controls. ATbar has several advanced Accessibility functions on top of the ability to change page styles, including Text-To-Speech and Dictionary lookup. Note that if you change styles with ATbar, they will '''not''' persist between pages as they do with the native functions, nor are you currently able to save them.
Ticking the checkbox will cause ATbar to be automatically loaded each time you visit a page containing the Accessibility block.
You can find out more about ATbar's functions by clicking the [[Image:Accessibility_help.png]] icon on the right of the bar itself.

[[Category:Block]]

File:Accessibility help.png

2011-01-18T14:13:01Z

Marxjohnson:

File:Accessibility atbar.png

2011-01-18T14:03:25Z

Marxjohnson: Accessibility block ATbar contols

Accessibility block ATbar contols

File:Accessibility colours.png

2011-01-18T14:03:08Z

Marxjohnson: Accessibility block colour scheme button

Accessibility block colour scheme button

File:Accessibility save.png

2011-01-18T14:02:43Z

Marxjohnson: Accessibility block save button

Accessibility block save button

File:Accessibility A+.png

2011-01-18T14:02:19Z

Marxjohnson: Accessibility block increase text size button

Accessibility block increase text size button

File:Accessibility A-.png

2011-01-18T14:02:06Z

Marxjohnson: Accessibility block decrease text size button

Accessibility block decrease text size button

File:Accessibility A.png

2011-01-18T14:01:31Z

Marxjohnson: Accessibility Block Text size reset button

Accessibility Block Text size reset button

Quick Find List Block

2011-01-18T13:36:59Z

Marxjohnson:

This block allows users to be found quickly by use of AJAX searching.
If Javascript is not available, it will fall back to use PHP forms.

=== Configuration options: ===

When it is first added to a page, it will be configured to search All Users. Configure the block as below to narrow this down by role.

The first option is the role the the searched users are to have; if the block is in a course it will find users with that role assigned in that course (not inherited), if it is on the front page/my moodle it will search for users with that role anywhere.

The second option allows you to define the text to display for each user. This can be any combination of their First name, Last name and Username. Enter the place holders as described on the form to define the format.

The third option allows the list to link to a page other than the users' profiles, for example setting it to "http://your.moodle.site/blog/index.php?userid=" would make all the links point to the users' blogs.

===Usage===

To use it just start typing any part of the users name into the box, as you type the list of names will appear and be narrowed down. Once you can see the user you want to find just click on their name.

[[Category:Block]]

Quick Course List Block

2011-01-18T13:36:35Z

Marxjohnson:

This block allows courses to accessed quickly by use of AJAX searching.
If Javascript is not available, it will fall back to use PHP forms.

This block requires no configuration.

===Usage===

Start typing the Full Name or Short Name of the course you wish to find. The results will be narrowed down as you type. When the course you want to access is displayed, simply click the link.

The search also supports SQL-Style wildcards: <tt>_</tt> will match 1 character, <tt>%</tt> will match any number of characters. E.G. to match courses starting with <tt>A1C</tt> or <tt>A2C</tt>, you could enter <tt>A_C</tt>. You only need to use <tt>%</tt> if you require a wildcard in the middle of a string - they are implied at the start and the end (so searching for <tt>SCI</tt> is the same as <tt>%SCI%</tt>). If you wish to search for a literal <tt>_</tt> or <tt>%</tt> precede them with a <tt>\</tt>, so to find a course name containing <tt>A_C</tt> you'd enter <tt>A\_C</tt>.

[[Category:Block]]

Quick Course List Block

2011-01-18T13:35:36Z

Marxjohnson: New page: This block allows courses to accessed quickly by use of AJAX searching. If Javascript is not available, it will fall back to use PHP forms. This block requires no configuration. ===Usage...

Quick Find List Block

2011-01-18T13:21:13Z

Marxjohnson: /* Configuration options: */

blocks/quickfindlist

2011-01-18T13:15:53Z

Marxjohnson: Redirecting to Quick Find List Block

#REDIRECT [[Quick Find List Block]]

Quick Find List Block

2011-01-18T13:15:38Z

Marxjohnson: Created page based on old blocks/quickfindlist page. Moved to bring in line with other pages in Blocks category.

This block allows users to be found quickly by use of AJAX searching.
If Javascript is not available, it will fall back to use PHP forms.

=== Configuration options: ===

When it is first added to a page, it will be configured to search All Users. Configure the block as below to narrow this down by role.

The first option is the role the the searched users are to have; if the block is in a course it will find users with that role assigned in that course (not inherited), if it is on the front page/my moodle it will search for users with that role anywhere.

The second option is optional; it allows the list to link to a page other than the users' profiles, for example setting it to "http://your.moodle.site/blog/index.php?userid=" would make all the links point to the users' blogs.

===Usage===

To use it just start typing any part of the users name into the box, as you type the list of names will appear and be narrowed down. Once you can see the user you want to find just click on their name.

[[Category:Blocks]]

Development talk:Module visibility and display

2010-12-23T14:38:53Z

Marxjohnson: /* Can this be used to create public/private course sites? */

UCLA is very excited about this feature. Currently we are using a patch that we call public/private (http://moodle.org/mod/data/view.php?d=13&rid=2768) to accomplish this functionality.

This proposed feature would remove the need to maintain our customized code.

Additionally, allowing the developers to add custom editing icons next to resources/activities without modifying core moodle is an excellent idea!
--[[User:Nick Thompson|Nick Thompson]] 17:37, 15 December 2010 (UTC)

------
+1 from me.--[[User:Tim Hunt|Tim Hunt]] 18:39, 15 December 2010 (UTC)

==A few comments==
# the modinfo could be a class with extra methods for the new stuff - instead of precalculating everything we could do the extra work only when necessary, it should be 100% compatible with current code and it could actually detect some parameter problems; another reason is there is no proper phpdocs which prevents autocomplete from working in IDEs
# icon and iconcomponent are supposed to be the new api, the mod/mymodule/iconname hack should be deprecated instead
# at the same time we should fix the known perf problems with the modinfo caching

Alternative proposal:
* create new interface module_info which is backwards compatible with old $cminfo, add hidden setting which specifies which class to use
* keep get_fast_modinfo() and make it return array of instances with module_info interface
* either use plugin_supports() for finding out if plugin contains view.php (false means no url, true default) - external urls and nonstandard urls are supposed to be implemented via view.php redirects such as in the mod/url
* or simply check if mod/xx/view.php exists (did we ever consider this solution?)
* all course page specific data could be initialised/computed only when necessary

Benefits could be a bit better performance, smaller course->modinfo and finally all the customisation could be done via modification/replacement of one class only.

--[[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 16:56, 19 December 2010 (UTC)

== Can this be used to create public/private course sites? ==

I'm not following all of this, but want to ask if this change would allow either of the following:

1. Guests can see course site, but certain resources or activities are invisible (and unavailable) unless logged in and enrolled in that class. (This is the purpose of UCLA's public/private customization mentioned by Nick Thompson above. We do this through Groupings and defaulting the course to public.)

2. Guests can NOT see the course site, but CAN access specific resources or activities if they've been marked as public and they have a URL to get there. (This is not how UCLA's is set up, but conceivably might be useful in certain situations.)

--Mike Franks 21:30, 22 December 2010 (UTC)

== Yes Please ==
Just to add that I think this is a fantastic idea. I was hoping to be able to do this with my Standard Slideshow module (allowing the slideshow to be optionally embedded directly on the course page, rather than just a separate view page).

[[User:Mark Johnson|Mark Johnson]] 14:38, 23 December 2010 (UTC)

Development:lib/formslib.php Form Definition

2010-12-14T11:34:24Z

Marxjohnson: Added documentation of filepicker with link to File API page

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform =& $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with a couple of important improvements:

# The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[Development:lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.

=== choosecoursefile ===
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$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->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Development:Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

<code php>
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</code>

You can supply a fourth param to htmleditor of an array of options :

<code php>

array(
'canUseHtmlEditor'=>'detect',
'rows' => 10,
'cols' => 65,
'width' => 0,
'height'=> 0,
'course'=> 0,
);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</code>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===

<code php>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

====multi-select====
<pre>
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===

Moodle 2.0+ only.

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

==setHelpButton==
<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

The possible choices here are in the function lockoptionsall in lib/javascript-static.js.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]

If you have problems creating php forms you may get them with form builder http://phpforms.net/tutorial/html-basics/form-builder.html

Capabilities/moodle/course:managegrades

2010-07-12T07:59:27Z

Marxjohnson:

*This capability has been defined (as of 1.7.1) to allow the user to manage grade exceptions in a given course.
*Grade exceptions allow the person with this capability to determine which students or assignments should or should not be present in the [[Grades|gradebook]].
*This appears to have been removed in Moodle 1.9. See [[Capabilities/moodle/grade:manage|moodle/grade:manage]]

====Legacy Role Default Settings====
{| border="1" cellspacing="0" cellpadding="2"
|-
! Legacy Role !! Inherit !! Allow !! Prevent !! Prohibit
|-
| Administrator || - || X || - || -
|-
| Course Creator || X || - || - || -
|-
| Teacher || - || X || - || -
|-
| Non-editing Teacher || X || - || - || -
|-
| Student || X || - || - || -
|-
| Guest || X || - || - || -
|-
| Authenticated User || X || - || - || -
|}

[[Category:Capabilities|Course]]

Development:lib/formslib.php Form Definition

2010-05-25T08:13:53Z

Marxjohnson:

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform =& $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with a couple of important improvements:

# The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[Development:lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.

=== choosecoursefile ===
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$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->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

<code php>
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</code>

You can supply a fourth param to htmleditor of an array of options :

<code php>

array(
'canUseHtmlEditor'=>'detect',
'rows' => 10,
'cols' => 65,
'width' => 0,
'height'=> 0,
'course'=> 0,
);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</code>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===

<code php>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

====multi-select====
<pre>
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===

Moodle 2.0+ only.

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

==setHelpButton==
<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

The possible choices here are in the function lockoptionsall in lib/javascript-static.js.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]

If you have problems creating php forms you may get them with form builder http://phpforms.net/tutorial/html-basics/form-builder.html

How to check your database for corruption

2010-03-03T08:56:51Z

Marxjohnson: Removed flippant comment about MySQL not being a "proper" database. This isn't useful to someone looking for help with database corruption.

Database corruption usually occurs as a result of a hardware (especially disk-based) failure, or when a disk becomes full. Typical symptoms are failure on login, with this message displayed:

Session Replace: Table './moodle/mdl_sessions2' is marked as crashed and should be repaired

This problem mostly seems to affect MySQL.

==MySQL==

The problem can be repaired using the mysqlcheck command (the command you type is in bold and we assume the database name is 'moodle' and its type is MySQL):

#'''mysqlcheck -u moodleuser -p --auto-repair moodle'''
Enter password:
moodle.adodb_logsql OK
moodle.mdl_assignment OK
moodle.mdl_assignment_submissions OK
...
moodle.mdl_log
error : Table './moodle/mdl_log' is marked as crashed and should be repaired
...
moodle.mdl_sessions2
error : Table './moodle/mdl_sessions2' is marked as crashed and should be repaired

Repairing tables
moodle_18_latest.mdl_log OK
moodle_18_latest.mdl_sessions2 OK

Your mysql database server must be running when executing the mysqlcheck command. If there are problems with the tables, the auto-repair option will fix them as shown above. Note that the repair process can take a long time to complete. Re-run the command again to double-check that all is OK.

Individual Moodle tables may be repaired using MySQL Admin/PHPMyAdmin as follows:
# In the databases section, select the Moodle database.
# Click the SQL tab, then in the "Run SQL query/queries on database moodle" field type <code>REPAIR TABLE mdl_tablename</code>
# Click the Go button.
For example, to repair the Moodle log tables, type <code>REPAIR TABLE mdl_log</code>

==Other databases==

As I said above, this issue normally only occurs with MySQL.

==See also==

*[http://moodle.org/mod/forum/discuss.php?d=58208#279638 Forum discussion] on a moodle database optimization script
*[[Performance#MySQL_performance | Performance Documentation]] on database repair and optimization
*[http://www.databasejournal.com/features/mysql/article.php/10897_3300511_2 Database Journal article on repairing database corruption in MySQL]

[[Category:Administrator]]
[[de:Wie man die Konsistenz der Moodle-Datenbank prüft]]