MDL-25475 lang string update thanks to Inaki Arenaza and Angelo Pappano
[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
08509f0a 67* /local/xxx/db/services.php - definition of web services and web service functions
aaff9f7f
PS
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
08509f0a 167Local plugin web services
168-------------------------
169During plugin installation or upgrade, the web service definitions are read
170from /local/nicehack/db/services.php and are automatically installed/updated in Moodle.
171
172sample files
173/local/nicehack/db/services.php
174$$functions = array (
175 'nicehack_hello_world' => array(
176 'classname' => 'local_nicehack_external',
177 'methodname' => 'hello_world',
178 'classpath' => 'local/nicehack/externallib.php',
179 'description' => 'Get hello world string',
180 'type' => 'read',
181 ),
182);
183$services = array(
184 'Nice hack service 1' => array(
185 'functions' => array ('nicehack_hello_world'),
186 'enabled'=>1,
187 ),
188);
189
190
191You will need to write the /local/nicehack/externallib.php - external functions
192description and code. See some examples from the core files (/user/externallib.php,
193/group/externallib.php...).
194
c6eb9bc6 195
72b4b0ef
PS
196Other local customisation files
197===============================
c6eb9bc6 198
17da2e6f 199Customised site defaults
200------------------------
201Different default site settings can be stored in file /local/defaults.php.
202These new defaults are used during installation, upgrade and later are
72b4b0ef
PS
203displayed as default values in admin settings. This means that the content
204of the defaults files is usually updated BEFORE installation or upgrade.
205
206These customised defaults are useful especially when using CLI tools
207for installation and upgrade.
17da2e6f 208
209Sample /local/defaults.php file content:
210<?php
72b4b0ef
PS
211$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
212$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
17da2e6f 213$defaults['moodlecourse']['numsections'] = 11;
72b4b0ef 214$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
17da2e6f 215
216First bracket contains string from column plugin of config_plugins table.
217Second bracket is the name of setting. In the admin settings UI the plugin and
218name of setting is separated by "|".
219
72b4b0ef 220The values usually correspond to the raw string in config table, with the exception
54f88b07 221of comma separated lists that are usually entered as real arrays.
72b4b0ef
PS
222
223Please note that not all settings are converted to admin_tree,
224they are mostly intended to be set directly in config.php.
17da2e6f 225
226
72b4b0ef 2272.0 pre-upgrade script
54f88b07 228----------------------
17da2e6f 229You an use /local/upgrade_pre20.php script for any code that needs to
72b4b0ef
PS
230be executed before the main upgrade to 2.0. Most probably this will
231be used for undoing of old hacks that would otherwise break normal
2322.0 upgrade.
17da2e6f 233
2b40710c
PS
234This file is just included directly, there does not need to be any
235function inside. If the execution stops the script is executed again
236during the next upgrade. The first execution of lib/db/upgrade.php
237increments the version number and the pre upgrade script is not
238executed any more.
239
17da2e6f 240
241
43266b40 2421.9.x upgrade notes
54f88b07 243===================
43266b40
PS
2441.9.x contains basic support for local hacks placed directly into
245/local/ directory. This old local API was completely removed and can
246not be used any more in 2.0. All old customisations need to be
247migrated to new local plugins before running of the 2.0 upgrade script.
248
249
250
72b4b0ef 251Other site customisation outside of "/local/" directory
54f88b07 252=======================================================
17da2e6f 253
254Local language pack modifications
255---------------------------------
256Moodle supports other type of local customisation of standard language
257packs. If you want to create your own language pack based on another
258language create new dataroot directory with "_local" suffix, for example
259following file with content changes string "Login" to "Sign in":
3a915b06 260moodledata/lang/en_local
17da2e6f 261<?php
262 $string['login'] = 'Sign in';
17da2e6f 263
264See also http://docs.moodle.org/en/Language_editing
72b4b0ef
PS
265
266
267Custom script injection
54f88b07 268-----------------------
72b4b0ef
PS
269Very old customisation option that allows you to modify scripts by injecting
270code right after the require 'config.php' call.
271
272This setting is enabled by manually setting $CFG->customscripts variable
273in config.php script. The value is expected to be full path to directory
274with the same structure as dirroot. Please note this hack only affects
275files that actually include the config.php!
276
277Examples:
278* disable one specific moodle page without code modification
54f88b07 279* alter page parameters on the fly