// This file is part of Moodle - http://moodle.org/ // // Moodle is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // Moodle is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** * Readme file for local customisations * * @package local * @copyright 2009 Petr Skoda (http://skodak.org) * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ Local customisations directory ============================== This directory is the recommended place for local customisations. Wherever possible, customisations should be written using one of the standard plug-in points like modules, blocks, auth plugins, themes, etc. See also http://docs.moodle.org/dev/Local_customisation for more information. Directory structure ------------------- This directory has standard plugin structure. All standard plugin features are supported. There may be some extra files with special meaning in /local/. Sample /local/ directory listing: /local/nicehack/ - first customisation plugin /local/otherhack/ - other customisation plugin /local/preupgrade.php - executed before each core upgrade, use $version and $CFG->version if you need to tweak specific local hacks /local/defaults.php - custom admin setting defaults 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/pluginname/version.php - version of script (must be incremented after changes) * /local/pluginname/db/install.xml - executed during install (new version.php found) * /local/pluginname/db/install.php - executed right after install.xml * /local/pluginname/db/uninstall.php - executed during uninstallation * /local/pluginname/db/upgrade.php - executed after version.php change * /local/pluginname/db/access.php - definition of capabilities * /local/pluginname/db/events.php - event handlers and subscripts * /local/pluginname/db/messages.php - messaging registration * /local/pluginname/db/services.php - definition of web services and web service functions * /local/pluginname/db/subplugins.php - list of subplugins types supported by this local plugin * /local/pluginname/lang/en/local_pluginname.php - language file * /local/pluginname/settings.php - admin settings Local plugin version specification ---------------------------------- version.php is mandatory for most of the standard plugin infrastructure. The version number must be incremented most plugin changes, the changed version tells Moodle to invalidate all caches, do db upgrades if necessary, install new capabilities, register event handlers, etc. Example: /local/nicehack/version.php version = 2010022400; // The (date) version of this plugin $plugin->requires = 2010021900; // Requires this Moodle version Local plugin capabilities ------------------------- Each local plugin may define own capabilities. It is not recommended to define capabilities belonging to other plugins here, but it should work too. /local/nicehack/access.php content array( 'captype' => 'read', 'contextlevel' => CONTEXT_SYSTEM, ), ); Local plugin language strings ----------------------------- If customisation needs new strings it is recommended to use normal plugin strings. sample language file /local/nicehack/lang/en/local_nicehack.php add('root', new admin_category('tweaks', 'Custom tweaks')); $ADMIN->add('tweaks', new admin_externalpage('nicehackery', 'Tweak something', $CFG->wwwroot.'/local/nicehack/setuppage.php')); Or if you want a new standard settings page for the plugin, inside the local plugins category: add('localplugins', $settings); $settings->add(new admin_setting_configtext('local_thisplugin/option', 'Option', 'Information about this option', 100, PARAM_INT)); } Local plugin event handlers --------------------------- Events are intended primarily for communication "core --> plugins". (It should not be use in opposite direction!) In theory it could be also used for "plugin --> plugin" communication too. The list of core events is documented in lib/db/events.php sample files /local/nicehack/db/events.php $handlers = array ( 'user_deleted' => array ( 'handlerfile' => '/local/nicehack/lib.php', 'handlerfunction' => 'nicehack_userdeleted_handler', 'schedule' => 'instant' ), ); NOTE: events are not yet fully implemented in current Moodle 2.0dev. Local plugin database tables ---------------------------- XMLDB editors is the recommended tool. Please note that modification of core table structure is highly discouraged. If you really really really need to modify core tables you might want to do that in install.php and later upgrade.php Note: it is forbidden to manually modify the DB structure, without corresponding changes in install.xml files. List of upgrade related files: /local/nicehack/db/install.xml - contains XML definition of new tables /local/nicehack/db/install.php - executed after db creation, may be also used for general install code /local/nicehack/db/upgrade.php - executed when version changes Local plugin web services ------------------------- During plugin installation or upgrade, the web service definitions are read from /local/nicehack/db/services.php and are automatically installed/updated in Moodle. sample files /local/nicehack/db/services.php $$functions = array ( 'nicehack_hello_world' => array( 'classname' => 'local_nicehack_external', 'methodname' => 'hello_world', 'classpath' => 'local/nicehack/externallib.php', 'description' => 'Get hello world string', 'type' => 'read', ), ); $services = array( 'Nice hack service 1' => array( 'functions' => array ('nicehack_hello_world'), 'enabled'=>1, ), ); You will need to write the /local/nicehack/externallib.php - external functions description and code. See some examples from the core files (/user/externallib.php, /group/externallib.php...). Local plugin navigation hooks ----------------------------- There are two functions that your plugin can define that allow it to extend the main navigation and the settings navigation. These two functions both need to be defined within /local/nicehack/lib.php. sample code 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 ---------------------- You an use /local/upgrade_pre20.php script for any code that needs to be executed before the main upgrade to 2.0. Most probably this will be used for undoing of old hacks that would otherwise break normal 2.0 upgrade. This file is just included directly, there does not need to be any function inside. If the execution stops the script is executed again during the next upgrade. The first execution of lib/db/upgrade.php increments the version number and the pre upgrade script is not executed any more. 1.9.x upgrade notes =================== 1.9.x contains basic support for local hacks placed directly into /local/ directory. This old local API was completely removed and can not be used any more in 2.0. All old customisations need to be migrated to new local plugins before running of the 2.0 upgrade script. Other site customisation outside of "/local/" directory ======================================================= Local language pack modifications --------------------------------- Moodle supports other type of local customisation of standard language packs. If you want to create your own language pack based on another language create new dataroot directory with "_local" suffix, for example following file with content changes string "Login" to "Sign in": moodledata/lang/en_local customscripts variable in config.php script. The value is expected to be full path to directory with the same structure as dirroot. Please note this hack only affects files that actually include the config.php! Examples: * disable one specific moodle page without code modification * alter page parameters on the fly