local/readme.txt

   1 // This file is part of Moodle - http://moodle.org/
   2 //
   3 // Moodle is free software: you can redistribute it and/or modify
   4 // it under the terms of the GNU General Public License as published by
   5 // the Free Software Foundation, either version 3 of the License, or
   6 // (at your option) any later version.
   7 //
   8 // Moodle is distributed in the hope that it will be useful,
   9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 // GNU General Public License for more details.
  12 //
  13 // You should have received a copy of the GNU General Public License
  14 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 /**
  17  * Readme file for local customisations
  18  *
  19  * @package    local
  20  * @copyright  2009 Petr Skoda (http://skodak.org)
  21  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  22  */
  23
  24 Local customisations directory
  25 ==============================
  26 This directory is the recommended place for local customisations.
  27 Wherever possible, customisations should be written using one
  28 of the standard plug-in points like modules, blocks, auth plugins, themes, etc.
  29
  30 See also http://docs.moodle.org/dev/Local_customisation for more
  31 information.
  32
  33
  34 Directory structure
  35 -------------------
  36 This directory has standard plugin structure. All standard plugin features
  37 are supported. There may be some extra files with special meaning in /local/.
  38
  39 Sample /local/ directory listing:
  40 /local/nicehack/         - first customisation plugin
  41 /local/otherhack/        - other customisation plugin
  42 /local/upgrade_pre20.php - one time upgrade and migration script which is
  43                            executed before main 2.0 upgrade starts
  44 /local/defaults.php      - custom admin setting defaults
  45
  46
  47
  48 Local plugins
  49 =============
  50 Local plugins are used in cases when no standard plugin fits, examples are:
  51 * event consumers communicating with external systems
  52 * custom definitions of web services and external functions
  53 * applications that extend moodle at the system level (hub server, amos server, etc.)
  54 * new database tables used in core hacks (discouraged)
  55 * new capability definitions used in core hacks
  56 * custom admin settings
  57
  58 Standard plugin features:
  59 * /local/pluginname/db/version.php - version of script (must be incremented after changes)
  60 * /local/pluginname/db/install.xml - executed during install (new version.php found)
  61 * /local/pluginname/db/install.php - executed right after install.xml
  62 * /local/pluginname/db/uninstall.php - executed during uninstallation
  63 * /local/pluginname/db/upgrade.php - executed after version.php change
  64 * /local/pluginname/db/access.php - definition of capabilities
  65 * /local/pluginname/db/events.php - event handlers and subscripts
  66 * /local/pluginname/db/messages.php - messaging registration
  67 * /local/pluginname/db/services.php - definition of web services and web service functions
  68 * /local/pluginname/lang/en/local_pluginname.php - language file
  69 * /local/pluginname/settings.php - admin settings
  70
  71
  72 Local plugin version specification
  73 ----------------------------------
  74 version.php is mandatory for most of the standard plugin infrastructure.
  75 The version number must be incremented most plugin changes, the changed
  76 version tells Moodle to invalidate all caches, do db upgrades if necessary,
  77 install new capabilities, register event handlers, etc.
  78
  79 Example:
  80 /local/nicehack/version.php
  81 <?php
  82 $plugin->version  = 2010022400;   // The (date) version of this plugin
  83 $plugin->requires = 2010021900;   // Requires this Moodle version
  84
  85
  86 Local plugin capabilities
  87 -------------------------
  88 Each local plugin may define own capabilities. It is not recommended to define
  89 capabilities belonging to other plugins here, but it should work too.
  90
  91 /local/nicehack/access.php content
  92 <?php
  93 $local_nicehack_capabilities = array(
  94     'local/nicehack:nicecapability' => array(
  95         'captype' => 'read',
  96         'contextlevel' => CONTEXT_SYSTEM,
  97     ),
  98 );
  99
 100
 101 Local plugin language strings
 102 -----------------------------
 103 If customisation needs new strings it is recommended to use normal plugin
 104 strings.
 105
 106 sample language file /local/nicehack/lang/en/local_nicehack.php
 107 <?php
 108 $string['hello'] = 'Hi {$a}';
 109 $string['nicehack:nicecapability'] = 'Some capability';
 110
 111
 112 use of the new string in code:
 113 echo get_string('hello', 'local_nicehack', 'petr');
 114
 115
 116 Local plugin admin menu items
 117 -----------------------------
 118 It is possible to add new items and categories to the admin_tree block.
 119 I you need to define new admin setting classes put them into separate
 120 file and require_once() from settings.php
 121
 122 For example if you want to add new external page use following
 123 /local/nicehack/settings.php
 124 <?php
 125 $ADMIN->add('root', new admin_category('tweaks', 'Custom tweaks'));
 126 $ADMIN->add('tweaks', new admin_externalpage('nicehackery', 'Tweak something',
 127             $CFG->wwwroot.'/local/nicehack/setuppage.php'));
 128
 129 Or if you want a new standard settings page for the plugin, inside the local
 130 plugins category:
 131 <?php
 132 defined('MOODLE_INTERNAL') || die;
 133
 134 if ($hassiteconfig) { // needs this condition or there is error on login page
 135     $settings = new admin_settingpage('local_thisplugin', 'This plugin');
 136     $ADMIN->add('localplugins', $settings);
 137
 138     $settings->add(new admin_setting_configtext('local_thisplugin/option',
 139         'Option', 'Information about this option', 100, PARAM_INT));
 140 }
 141
 142 Local plugin event handlers
 143 ---------------------------
 144 Events are intended primarily for communication "core --> plugins".
 145 (It should not be use in opposite direction!)
 146 In theory it could be also used for "plugin --> plugin" communication too.
 147 The list of core events is documented in lib/db/events.php
 148
 149 sample files
 150 /local/nicehack/db/events.php
 151 $handlers = array (
 152     'user_deleted' => array (
 153          'handlerfile'      => '/local/nicehack/lib.php',
 154          'handlerfunction'  => 'nicehack_userdeleted_handler',
 155          'schedule'         => 'instant'
 156      ),
 157 );
 158
 159 NOTE: events are not yet fully implemented in current Moodle 2.0dev.
 160
 161
 162 Local plugin database tables
 163 ----------------------------
 164 XMLDB editors is the recommended tool. Please note that modification
 165 of core table structure is highly discouraged.
 166
 167 If you really really really need to modify core tables you might want to do
 168 that in install.php and later upgrade.php
 169
 170 Note: it is forbidden to manually modify the DB structure, without corresponding
 171       changes in install.xml files.
 172
 173 List of upgrade related files:
 174 /local/nicehack/db/install.xml - contains XML definition of new tables
 175 /local/nicehack/db/install.php - executed after db creation, may be also used
 176                                  for general install code
 177 /local/nicehack/db/upgrade.php - executed when version changes
 178
 179
 180 Local plugin web services
 181 -------------------------
 182 During plugin installation or upgrade, the web service definitions are read
 183 from /local/nicehack/db/services.php and are automatically installed/updated in Moodle.
 184
 185 sample files
 186 /local/nicehack/db/services.php
 187 $$functions = array (
 188     'nicehack_hello_world' => array(
 189                 'classname'   => 'local_nicehack_external',
 190                 'methodname'  => 'hello_world',
 191                 'classpath'   => 'local/nicehack/externallib.php',
 192                 'description' => 'Get hello world string',
 193                 'type'        => 'read',
 194     ),
 195 );
 196 $services = array(
 197         'Nice hack service 1' => array(
 198                 'functions' => array ('nicehack_hello_world'),
 199                 'enabled'=>1,
 200         ),
 201 );
 202
 203
 204 You will need to write the /local/nicehack/externallib.php - external functions
 205 description and code. See some examples from the core files (/user/externallib.php,
 206 /group/externallib.php...).
 207
 208
 209 Other local customisation files
 210 ===============================
 211
 212 Customised site defaults
 213 ------------------------
 214 Different default site settings can be stored in file /local/defaults.php.
 215 These new defaults are used during installation, upgrade and later are
 216 displayed as default values in admin settings. This means that the content
 217 of the defaults files is usually updated BEFORE installation or upgrade.
 218
 219 These customised defaults are useful especially when using CLI tools
 220 for installation and upgrade.
 221
 222 Sample /local/defaults.php file content:
 223 <?php
 224 $defaults['moodle']['forcelogin'] = 1;  // new default for $CFG->forcelogin
 225 $defaults['scorm']['maxgrade'] = 20;    // default for get_config('scorm', 'maxgrade')
 226 $defaults['moodlecourse']['numsections'] = 11;
 227 $defaults['moodle']['hiddenuserfields'] = array('city', 'country');
 228
 229 First bracket contains string from column plugin of config_plugins table.
 230 Second bracket is the name of setting. In the admin settings UI the plugin and
 231 name of setting is separated by "|".
 232
 233 The values usually correspond to the raw string in config table, with the exception
 234 of comma separated lists that are usually entered as real arrays.
 235
 236 Please note that not all settings are converted to admin_tree,
 237 they are mostly intended to be set directly in config.php.
 238
 239
 240 2.0 pre-upgrade script
 241 ----------------------
 242 You an use /local/upgrade_pre20.php script for any code that needs to
 243 be executed before the main upgrade to 2.0. Most probably this will
 244 be used for undoing of old hacks that would otherwise break normal
 245 2.0 upgrade.
 246
 247 This file is just included directly, there does not need to be any
 248 function inside. If the execution stops the script is executed again
 249 during the next upgrade. The first execution of lib/db/upgrade.php
 250 increments the version number and the pre upgrade script is not
 251 executed any more.
 252
 253
 254
 255 1.9.x upgrade notes
 256 ===================
 257 1.9.x contains basic support for local hacks placed directly into
 258 /local/ directory. This old local API was completely removed and can
 259 not be used any more in 2.0. All old customisations need to be
 260 migrated to new local plugins before running of the 2.0 upgrade script.
 261
 262
 263
 264 Other site customisation outside of "/local/" directory
 265 =======================================================
 266
 267 Local language pack modifications
 268 ---------------------------------
 269 Moodle supports other type of local customisation of standard language
 270 packs. If you want to create your own language pack based on another
 271 language create new dataroot directory with "_local" suffix, for example
 272 following file with content changes string "Login" to "Sign in":
 273 moodledata/lang/en_local
 274 <?php
 275   $string['login'] = 'Sign in';
 276
 277 See also http://docs.moodle.org/en/Language_editing
 278
 279
 280 Custom script injection
 281 -----------------------
 282 Very old customisation option that allows you to modify scripts by injecting
 283 code right after the require 'config.php' call.
 284
 285 This setting is enabled by manually setting $CFG->customscripts variable
 286 in config.php script. The value is expected to be full path to directory
 287 with the same structure as dirroot. Please note this hack only affects
 288 files that actually include the config.php!
 289
 290 Examples:
 291 * disable one specific moodle page without code modification
 292 * alter page parameters on the fly