MDL-17376 some more upgrade info
[moodle.git] / local / readme.txt
CommitLineData
17da2e6f 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
24Local customisations directory
25==============================
6f5e0852 26This directory is the recommended place for local customisations.
72b4b0ef
PS
27Wherever possible, customisations should be written using one
28of the standard plug-in points like modules, blocks, auth plugins, themes, etc.
17da2e6f 29
30See also http://docs.moodle.org/en/Development:Local_customisation for more
31information.
32
33
34Directory structure
35-------------------
36This directory has standard plugin structure. All standard plugin features
37are supported. There may be some extra files with special meaning in /local/.
38
39Sample /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
72b4b0ef 43 executed before main 2.0 upgrade starts
17da2e6f 44/local/defaults.php - custom admin setting defaults
45
46
72b4b0ef
PS
47
48Local plugins
49===============================
50Local 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
59Local plugin version specification
60-------------------
61version.php is mandatory for most of the standard plugin infrastructure.
62The version number must be incremented most plugin changes, the changed
63version tells Moodle to invalidate all caches, do db upgrades if necessary,
64install new capabilities, register event handlers, etc.
65
66Example:
67/local/nicehack/version.php
68<?php
69$plugin->version = 2010022400; // The (date) version of this plugin
70$plugin->requires = 2010021900; // Requires this Moodle version
71
72
73Local plugin capabilities
17da2e6f 74-------------------
72b4b0ef 75Each local plugin may define own capabilities. It is not recommended to define
17da2e6f 76capabilities belonging to other plugins here, but it should work too.
77
78/local/nicehack/access.php content
79<?php
80$local_nicehack_capabilities = array(
81 'local/nicehack:nicecapability' => array(
82 'captype' => 'read',
83 'contextlevel' => CONTEXT_SYSTEM,
84 ),
85);
17da2e6f 86
87
72b4b0ef 88Local plugin language strings
17da2e6f 89-----------------------
90If customisation needs new strings it is recommended to use normal plugin
91strings.
92
3a915b06 93sample language file /local/nicehack/lang/en/local_nicehack.php
17da2e6f 94<?php
72b4b0ef 95$string['hello'] = 'Hi {$a}';
17da2e6f 96$string['nicehack:nicecapability'] = 'Some capability';
17da2e6f 97
72b4b0ef
PS
98
99use of the new string in code:
17da2e6f 100echo get_string('hello', 'local_nicehack', 'petr');
101
102
72b4b0ef 103Local plugin admin menu items
17da2e6f 104----------------------
105It is possible to add new items and categories to the admin_tree block.
106I you need to define new admin setting classes put them into separate
107file and require_once() from settings.php
108
109For example if you want to add new external page use following
110/local/nicehack/settings.php
111<?php
112$ADMIN->add('root', new admin_category('tweaks', 'Custom tweaks'));
113$ADMIN->add('tweaks', new admin_externalpage('nicehackery', 'Tweak something',
114 $CFG->wwwroot.'/local/nicehack/setuppage.php'));
17da2e6f 115
116
72b4b0ef 117Local plugin event handlers
17da2e6f 118---------------------
72b4b0ef
PS
119Events are intended primarily for communication "core --> plugins".
120(It should not be use in opposite direction!)
121In theory it could be also used for "plugin --> plugin" communication too.
122The list of core events is documented in lib/db/events.php
17da2e6f 123
124sample files
125/local/nicehack/db/events.php
126$handlers = array (
127 'user_deleted' => array (
128 'handlerfile' => '/local/nicehack/lib.php',
6f5e0852 129 'handlerfunction' => 'nicehack_userdeleted_handler',
17da2e6f 130 'schedule' => 'instant'
131 ),
132);
133
72b4b0ef 134NOTE: events are not yet fully implemented in current Moodle 2.0dev.
17da2e6f 135
136
72b4b0ef 137Local plugin database tables
17da2e6f 138----------------
139XMLDB editors is the recommended tool. Please note that modification
140of core table structure is highly discouraged.
141
142If you really really really need to modify core tables you might want to do
143that in install.php and later upgrade.php
144
72b4b0ef
PS
145Note: it is forbidden to manually modify the DB structure, without corresponding
146 changes in install.xml files.
147
17da2e6f 148List of upgrade related files:
149/local/nicehack/db/install.xml - contains XML definition of new tables
150/local/nicehack/db/install.php - executed after db creation, may be also used
151 for general install code
152/local/nicehack/db/upgrade.php - executed when version changes
17da2e6f 153
154
c6eb9bc6 155
72b4b0ef
PS
156Other local customisation files
157===============================
c6eb9bc6 158
17da2e6f 159Customised site defaults
160------------------------
161Different default site settings can be stored in file /local/defaults.php.
162These new defaults are used during installation, upgrade and later are
72b4b0ef
PS
163displayed as default values in admin settings. This means that the content
164of the defaults files is usually updated BEFORE installation or upgrade.
165
166These customised defaults are useful especially when using CLI tools
167for installation and upgrade.
17da2e6f 168
169Sample /local/defaults.php file content:
170<?php
72b4b0ef
PS
171$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
172$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
17da2e6f 173$defaults['moodlecourse']['numsections'] = 11;
72b4b0ef 174$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
17da2e6f 175
176First bracket contains string from column plugin of config_plugins table.
177Second bracket is the name of setting. In the admin settings UI the plugin and
178name of setting is separated by "|".
179
72b4b0ef
PS
180The values usually correspond to the raw string in config table, with the exception
181of comma separated lists that are usually entered as real arrays.
182
183Please note that not all settings are converted to admin_tree,
184they are mostly intended to be set directly in config.php.
17da2e6f 185
186
72b4b0ef
PS
1872.0 pre-upgrade script
188-------------------
17da2e6f 189You an use /local/upgrade_pre20.php script for any code that needs to
72b4b0ef
PS
190be executed before the main upgrade to 2.0. Most probably this will
191be used for undoing of old hacks that would otherwise break normal
1922.0 upgrade.
17da2e6f 193
2b40710c
PS
194This file is just included directly, there does not need to be any
195function inside. If the execution stops the script is executed again
196during the next upgrade. The first execution of lib/db/upgrade.php
197increments the version number and the pre upgrade script is not
198executed any more.
199
17da2e6f 200
201
43266b40
PS
2021.9.x upgrade notes
203===============================
2041.9.x contains basic support for local hacks placed directly into
205/local/ directory. This old local API was completely removed and can
206not be used any more in 2.0. All old customisations need to be
207migrated to new local plugins before running of the 2.0 upgrade script.
208
209
210
72b4b0ef 211Other site customisation outside of "/local/" directory
17da2e6f 212===============================
213
214Local language pack modifications
215---------------------------------
216Moodle supports other type of local customisation of standard language
217packs. If you want to create your own language pack based on another
218language create new dataroot directory with "_local" suffix, for example
219following file with content changes string "Login" to "Sign in":
3a915b06 220moodledata/lang/en_local
17da2e6f 221<?php
222 $string['login'] = 'Sign in';
17da2e6f 223
224See also http://docs.moodle.org/en/Language_editing
72b4b0ef
PS
225
226
227Custom script injection
228---------------------------------
229Very old customisation option that allows you to modify scripts by injecting
230code right after the require 'config.php' call.
231
232This setting is enabled by manually setting $CFG->customscripts variable
233in config.php script. The value is expected to be full path to directory
234with the same structure as dirroot. Please note this hack only affects
235files that actually include the config.php!
236
237Examples:
238* disable one specific moodle page without code modification
239* alter page parameters on the fly