6ad68097e5a0e3f534574828a9f6e2daaee47ca1
[moodle.git] / 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/>.
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  */
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.
30 See also http://docs.moodle.org/en/Development:Local_customisation for more
31 information.
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/.
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
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
59 Local plugin version specification
60 -------------------
61 version.php is mandatory for most of the standard plugin infrastructure.
62 The version number must be incremented most plugin changes, the changed
63 version tells Moodle to invalidate all caches, do db upgrades if necessary,
64 install new capabilities, register event handlers, etc.
66 Example:
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
73 Local plugin capabilities
74 -------------------
75 Each local plugin may define own capabilities. It is not recommended to define
76 capabilities belonging to other plugins here, but it should work too.
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 );
88 Local plugin language strings
89 -----------------------
90 If customisation needs new strings it is recommended to use normal plugin
91 strings.
93 sample language file /local/nicehack/lang/en/local_nicehack.php
94 <?php
95 $string['hello'] = 'Hi {$a}';
96 $string['nicehack:nicecapability'] = 'Some capability';
99 use of the new string in code:
100 echo get_string('hello', 'local_nicehack', 'petr');
103 Local plugin admin menu items
104 ----------------------
105 It is possible to add new items and categories to the admin_tree block.
106 I you need to define new admin setting classes put them into separate
107 file and require_once() from settings.php
109 For 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'));
117 Local plugin event handlers
118 ---------------------
119 Events are intended primarily for communication "core --> plugins".
120 (It should not be use in opposite direction!)
121 In theory it could be also used for "plugin --> plugin" communication too.
122 The list of core events is documented in lib/db/events.php
124 sample files
125 /local/nicehack/db/events.php
126 $handlers = array (
127     'user_deleted' => array (
128          'handlerfile'      => '/local/nicehack/lib.php',
129          'handlerfunction'  => 'nicehack_userdeleted_handler',
130          'schedule'         => 'instant'
131      ),
132 );
134 NOTE: events are not yet fully implemented in current Moodle 2.0dev.
137 Local plugin database tables
138 ----------------
139 XMLDB editors is the recommended tool. Please note that modification
140 of core table structure is highly discouraged.
142 If you really really really need to modify core tables you might want to do
143 that in install.php and later upgrade.php
145 Note: it is forbidden to manually modify the DB structure, without corresponding
146       changes in install.xml files.
148 List 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
156 Other local customisation files
157 ===============================
159 Customised site defaults
160 ------------------------
161 Different default site settings can be stored in file /local/defaults.php.
162 These new defaults are used during installation, upgrade and later are
163 displayed as default values in admin settings. This means that the content
164 of the defaults files is usually updated BEFORE installation or upgrade.
166 These customised defaults are useful especially when using CLI tools
167 for installation and upgrade.
169 Sample /local/defaults.php file content:
170 <?php
171 $defaults['moodle']['forcelogin'] = 1;  // new default for $CFG->forcelogin
172 $defaults['scorm']['maxgrade'] = 20;    // default for get_config('scorm', 'maxgrade')
173 $defaults['moodlecourse']['numsections'] = 11;
174 $defaults['moodle']['hiddenuserfields'] = array('city', 'country');
176 First bracket contains string from column plugin of config_plugins table.
177 Second bracket is the name of setting. In the admin settings UI the plugin and
178 name of setting is separated by "|".
180 The values usually correspond to the raw string in config table, with the exception
181 of comma separated lists that are usually entered as real arrays. 
183 Please note that not all settings are converted to admin_tree,
184 they are mostly intended to be set directly in config.php.
187 1.9.x upgrade notes
188 -------------------
189 1.9.x contains basic support for local hacks placed directly into
190 /local/ directory. This old local API was completely removed and can
191 not be used any more in 2.0. All old customisations need to be
192 migrated to new local plugins before running of the 2.0 upgrade script.
195 2.0 pre-upgrade script
196 -------------------
197 You an use /local/upgrade_pre20.php script for any code that needs to
198 be executed before the main upgrade to 2.0. Most probably this will
199 be used for undoing of old hacks that would otherwise break normal
200 2.0 upgrade.
204 Other site customisation outside of "/local/" directory
205 ===============================
207 Local language pack modifications
208 ---------------------------------
209 Moodle supports other type of local customisation of standard language
210 packs. If you want to create your own language pack based on another
211 language create new dataroot directory with "_local" suffix, for example
212 following file with content changes string "Login" to "Sign in":
213 moodledata/lang/en_local
214 <?php
215   $string['login'] = 'Sign in';
217 See also http://docs.moodle.org/en/Language_editing
220 Custom script injection
221 ---------------------------------
222 Very old customisation option that allows you to modify scripts by injecting
223 code right after the require 'config.php' call.
225 This setting is enabled by manually setting $CFG->customscripts variable
226 in config.php script. The value is expected to be full path to directory
227 with the same structure as dirroot. Please note this hack only affects
228 files that actually include the config.php!
230 Examples:
231 * disable one specific moodle page without code modification
232 * alter page parameters on the fly