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