Automatically generated installer lang files
[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
728ebac7 30See also http://docs.moodle.org/dev/Local_customisation for more
17da2e6f 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 58Standard plugin features:
b5a64b11 59* /local/pluginname/version.php - version of script (must be incremented after changes)
2528fe14
SM
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
aaff9f7f 70
72b4b0ef
PS
71
72Local plugin version specification
54f88b07 73----------------------------------
72b4b0ef
PS
74version.php is mandatory for most of the standard plugin infrastructure.
75The version number must be incremented most plugin changes, the changed
76version tells Moodle to invalidate all caches, do db upgrades if necessary,
77install new capabilities, register event handlers, etc.
78
79Example:
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
86Local plugin capabilities
54f88b07 87-------------------------
72b4b0ef 88Each local plugin may define own capabilities. It is not recommended to define
17da2e6f 89capabilities 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);
17da2e6f 99
100
72b4b0ef 101Local plugin language strings
54f88b07 102-----------------------------
17da2e6f 103If customisation needs new strings it is recommended to use normal plugin
104strings.
105
3a915b06 106sample language file /local/nicehack/lang/en/local_nicehack.php
17da2e6f 107<?php
72b4b0ef 108$string['hello'] = 'Hi {$a}';
17da2e6f 109$string['nicehack:nicecapability'] = 'Some capability';
17da2e6f 110
72b4b0ef
PS
111
112use of the new string in code:
17da2e6f 113echo get_string('hello', 'local_nicehack', 'petr');
114
115
72b4b0ef 116Local plugin admin menu items
54f88b07 117-----------------------------
17da2e6f 118It is possible to add new items and categories to the admin_tree block.
119I you need to define new admin setting classes put them into separate
120file and require_once() from settings.php
121
122For 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'));
17da2e6f 128
9ea98a6e
SM
129Or if you want a new standard settings page for the plugin, inside the local
130plugins category:
2528fe14
SM
131<?php
132defined('MOODLE_INTERNAL') || die;
133
9ea98a6e
SM
134if ($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);
2528fe14 137
9ea98a6e
SM
138 $settings->add(new admin_setting_configtext('local_thisplugin/option',
139 'Option', 'Information about this option', 100, PARAM_INT));
140}
17da2e6f 141
72b4b0ef 142Local plugin event handlers
54f88b07 143---------------------------
72b4b0ef
PS
144Events are intended primarily for communication "core --> plugins".
145(It should not be use in opposite direction!)
146In theory it could be also used for "plugin --> plugin" communication too.
147The list of core events is documented in lib/db/events.php
17da2e6f 148
149sample files
150/local/nicehack/db/events.php
151$handlers = array (
152 'user_deleted' => array (
153 'handlerfile' => '/local/nicehack/lib.php',
6f5e0852 154 'handlerfunction' => 'nicehack_userdeleted_handler',
17da2e6f 155 'schedule' => 'instant'
156 ),
157);
158
72b4b0ef 159NOTE: events are not yet fully implemented in current Moodle 2.0dev.
17da2e6f 160
161
72b4b0ef 162Local plugin database tables
54f88b07 163----------------------------
17da2e6f 164XMLDB editors is the recommended tool. Please note that modification
165of core table structure is highly discouraged.
166
167If you really really really need to modify core tables you might want to do
168that in install.php and later upgrade.php
169
72b4b0ef
PS
170Note: it is forbidden to manually modify the DB structure, without corresponding
171 changes in install.xml files.
172
17da2e6f 173List 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
17da2e6f 178
179
08509f0a 180Local plugin web services
181-------------------------
182During plugin installation or upgrade, the web service definitions are read
183from /local/nicehack/db/services.php and are automatically installed/updated in Moodle.
184
185sample 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
204You will need to write the /local/nicehack/externallib.php - external functions
205description and code. See some examples from the core files (/user/externallib.php,
206/group/externallib.php...).
207
a15e8b41
SH
208Local plugin navigation hooks
209-----------------------------
210There are two functions that your plugin can define that allow it to extend the main
211navigation and the settings navigation.
212These two functions both need to be defined within /local/nicehack/lib.php.
213
214sample code
215<?php
5c1f0d1f 216function local_nicehack_extends_navigation(global_navigation $nav) {
a15e8b41
SH
217 // $nav is the global navigation instance.
218 // Here you can add to and manipulate the navigation structure as you like.
5c1f0d1f
SH
219 // This callback was introduced in 2.0 as nicehack_extends_navigation(global_navigation $nav)
220 // In 2.3 support was added for the now preferred local_nicehack_extends_navigation(global_navigation $nav).
a15e8b41
SH
221}
222function local_nicehack_extends_settings_navigation(settings_navigation $nav, context $context) {
223 // $nav is the settings navigation instance.
224 // $context is the context the settings have been loaded for (settings is context specific)
225 // Here you can add to and manipulate the settings structure as you like.
226 // This callback was introduced in 2.3
227}
c6eb9bc6 228
72b4b0ef
PS
229Other local customisation files
230===============================
c6eb9bc6 231
17da2e6f 232Customised site defaults
233------------------------
234Different default site settings can be stored in file /local/defaults.php.
235These new defaults are used during installation, upgrade and later are
72b4b0ef
PS
236displayed as default values in admin settings. This means that the content
237of the defaults files is usually updated BEFORE installation or upgrade.
238
239These customised defaults are useful especially when using CLI tools
240for installation and upgrade.
17da2e6f 241
242Sample /local/defaults.php file content:
243<?php
72b4b0ef
PS
244$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
245$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
17da2e6f 246$defaults['moodlecourse']['numsections'] = 11;
72b4b0ef 247$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
17da2e6f 248
249First bracket contains string from column plugin of config_plugins table.
250Second bracket is the name of setting. In the admin settings UI the plugin and
251name of setting is separated by "|".
252
72b4b0ef 253The values usually correspond to the raw string in config table, with the exception
54f88b07 254of comma separated lists that are usually entered as real arrays.
72b4b0ef
PS
255
256Please note that not all settings are converted to admin_tree,
257they are mostly intended to be set directly in config.php.
17da2e6f 258
259
72b4b0ef 2602.0 pre-upgrade script
54f88b07 261----------------------
17da2e6f 262You an use /local/upgrade_pre20.php script for any code that needs to
72b4b0ef
PS
263be executed before the main upgrade to 2.0. Most probably this will
264be used for undoing of old hacks that would otherwise break normal
2652.0 upgrade.
17da2e6f 266
2b40710c
PS
267This file is just included directly, there does not need to be any
268function inside. If the execution stops the script is executed again
269during the next upgrade. The first execution of lib/db/upgrade.php
270increments the version number and the pre upgrade script is not
271executed any more.
272
17da2e6f 273
274
43266b40 2751.9.x upgrade notes
54f88b07 276===================
43266b40
PS
2771.9.x contains basic support for local hacks placed directly into
278/local/ directory. This old local API was completely removed and can
279not be used any more in 2.0. All old customisations need to be
280migrated to new local plugins before running of the 2.0 upgrade script.
281
282
283
72b4b0ef 284Other site customisation outside of "/local/" directory
54f88b07 285=======================================================
17da2e6f 286
287Local language pack modifications
288---------------------------------
289Moodle supports other type of local customisation of standard language
290packs. If you want to create your own language pack based on another
291language create new dataroot directory with "_local" suffix, for example
292following file with content changes string "Login" to "Sign in":
3a915b06 293moodledata/lang/en_local
17da2e6f 294<?php
295 $string['login'] = 'Sign in';
17da2e6f 296
297See also http://docs.moodle.org/en/Language_editing
72b4b0ef
PS
298
299
300Custom script injection
54f88b07 301-----------------------
72b4b0ef
PS
302Very old customisation option that allows you to modify scripts by injecting
303code right after the require 'config.php' call.
304
305This setting is enabled by manually setting $CFG->customscripts variable
306in config.php script. The value is expected to be full path to directory
307with the same structure as dirroot. Please note this hack only affects
308files that actually include the config.php!
309
310Examples:
311* disable one specific moodle page without code modification
54f88b07 312* alter page parameters on the fly