From 72b4b0efa9ec87542274ec914f0eea8d01d7b412 Mon Sep 17 00:00:00 2001 From: Petr Skoda Date: Wed, 19 May 2010 08:11:27 +0000 Subject: [PATCH] MDL-17376 towards production ready local customisations - docs update --- local/readme.txt | 122 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 86 insertions(+), 36 deletions(-) diff --git a/local/readme.txt b/local/readme.txt index 294e0613350..6ad68097e5a 100644 --- a/local/readme.txt +++ b/local/readme.txt @@ -24,9 +24,8 @@ 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. +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/en/Development:Local_customisation for more information. @@ -41,13 +40,39 @@ Sample /local/ directory listing: /local/nicehack/ - first customisation plugin /local/otherhack/ - other customisation plugin /local/upgrade_pre20.php - one time upgrade and migration script which is - executed before main 2.0 upgrade + executed before main 2.0 upgrade starts /local/defaults.php - custom admin setting defaults -Custom capabilities + +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 + + +Local plugin version specification ------------------- -Each plugin may define own capabilities. It is not recommended to define +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 @@ -58,25 +83,24 @@ $local_nicehack_capabilities = array( 'contextlevel' => CONTEXT_SYSTEM, ), ); -?> -Custom language strings +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 -use of the new string in code + +use of the new string in code: echo get_string('hello', 'local_nicehack', 'petr'); -Custom admin menu items +Local plugin admin menu items ---------------------- It is possible to add new items and categories to the admin_tree block. I you need to define new admin setting classes put them into separate @@ -88,15 +112,14 @@ For example if you want to add new external page use following $ADMIN->add('root', new admin_category('tweaks', 'Custom tweaks')); $ADMIN->add('tweaks', new admin_externalpage('nicehackery', 'Tweak something', $CFG->wwwroot.'/local/nicehack/setuppage.php')); -?> -Custom event handlers +Local plugin event handlers --------------------- -Events 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 +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 @@ -108,10 +131,10 @@ $handlers = array ( ), ); -NOTE: events are not yet fulyl implemented in current Moodle 2.0dev. +NOTE: events are not yet fully implemented in current Moodle 2.0dev. -Custom db tables +Local plugin database tables ---------------- XMLDB editors is the recommended tool. Please note that modification of core table structure is highly discouraged. @@ -119,53 +142,66 @@ 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/nicehack/version.php - version specification file -Version.php example -------------------- -/local/nicehack/version.php - -$plugin->version = 2010022400; // The (date) version of this plugin -$plugin->requires = 2010021900; // Requires this Moodle version +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. +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: 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 "|". -Please note that not all settings are converted to admin_tree yet. +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. 1.9.x upgrade notes ------------------- 1.9.x contains basic support for local hacks placed directly into -/local/ directory. This old local API is not supported any more in 2.0. +/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. + +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. +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. -Other customisation information +Other site customisation outside of "/local/" directory =============================== Local language pack modifications @@ -177,6 +213,20 @@ following file with content changes string "Login" to "Sign in": moodledata/lang/en_local See also http://docs.moodle.org/en/Language_editing + + +Custom script injection +--------------------------------- +Very old customisation option that allows you to modify scripts by injecting +code right after the require 'config.php' call. + +This setting is enabled by manually setting $CFG->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 \ No newline at end of file