Revision as of 07:03, 20 May 2010

Local customisations
Project state	Implemented, documenting
Tracker issue	MDL-17376, MDL-16438
Discussion	http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
Assignee	Petr Škoda (škoďák), some parts were originally proposed and implemented 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.

Custom /local/ plugins

Local plugins are used in cases when no standard plugin fits, examples are:

event consumers communicating with external systems
custom definitions of web services and external functions
applications that extend moodle at the system level (hub server, amos server, etc.)
new database tables used in core hacks (discouraged)
new capability definitions used in core hacks
custom admin settings

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 settings 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)

Other /local/ customisation files

Customised site defaults

Different default site settings can be stored in file /local/defaults.php. These new defaults are used during installation, upgrade and later are displayed as default values in admin settings. This means that the content of the defaults files is usually updated BEFORE installation or upgrade.

These customised defaults are useful especially when using CLI tools for installation and upgrade.

Sample /local/defaults.php file content: <?php $defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin $defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade') $defaults['moodlecourse']['numsections'] = 11; $defaults['moodle']['hiddenuserfields'] = array('city', 'country'); First bracket contains string from column plugin of config_plugins table. Second bracket is the name of setting. In the admin settings UI the plugin and name of setting is separated by "|".

The values usually correspond to the raw string in config table, with the exception of comma separated lists that are usually entered as real arrays.

Please note that not all settings are converted to admin_tree, they are mostly intended to be set directly in config.php.

2.0 pre-upgrade script

Customisations outside of /local/ directory

Forced settings

Local language customisations

Custom script injection

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()

Migration from old 1.9.x /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

Documentation

Local plugins: Difference between revisions