Local plugins

Local customisations
Project state	In progress
Tracker issue	MDL-17376, MDL-16438
Discussion	http://moodle.org/mod/forum/discuss.php?d=126017
Assignee	Petr Škoda (škoďák), original proposal and implementation in 1.9 by Penny Leach

Moodle 2.0

The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

/local/ plugins

Standard plugin features:

• /local/xxx/db/version.php - version of script (must be incremented after changes)
• /local/xxx/db/install.xml - executed during install (new version.php found)
• /local/xxx/db/install.php - executed right after install.xml
• /local/xxx/db/upgrade.php - executed after version.php change
• /local/xxx/db/access.php - definition of capabilities
• /local/xxx/db/events.php - event handlers and subscripts
• /local/xxx/db/messages.php - messaging registration
• /local/xxx/db/external.php - web services and external functions descriptions
• /local/xxx/lang/en/local_pluginname.php - language file

The xxx is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.

List of differences from normal plugins:

• always executed last during install/upgrade - guaranteed by order of plugins in get_plugin_types()
• are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
• can add admin settings to any page - loaded last when constructing admin tree
• do not need to have any UI - other plugins are usually visible somewhere
• some extra hooks (not implemented yet)

Migration from old local/

• local/* needs to be copied to new directory
• local/xxxx/db/install.php is intended for first installation, originally everything was in upgrade.php
• events are used instead of hooks
• upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

Customisations outside of /local/ directory

Direct code modifications

This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

Direct database modifications

Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

Local customisations in previous versions

Previous versions include only partial support for customisations in /local/ directory.

List of local customisations in 1.9.x:

• /local/cron.php - custom cron jobs
• /local/settings.php - custom admin settings
• /local/db/upgrade.php - general modifications
• /local/lang/* - custom strings
• /local/lib.php - local_delete_course()

See also

• Using Moodle Local Customisations forum discussion
• http://cvs.moodle.org/moodle/local/readme.txt?view=markup