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