MDL-51685 user: Support gravatar images in user_get_user_details
[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/dev/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/preupgrade.php    - executed before each core upgrade, use $version and $CFG->version
43                            if you need to tweak specific local hacks
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
58 Standard plugin features:
59 * /local/pluginname/version.php - version of script (must be incremented after changes)
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/db/subplugins.php - list of subplugins types supported by this local plugin
69 * /local/pluginname/lang/en/local_pluginname.php - language file
70 * /local/pluginname/settings.php - admin settings
73 Local plugin version specification
74 ----------------------------------
75 version.php is mandatory for most of the standard plugin infrastructure.
76 The version number must be incremented most plugin changes, the changed
77 version tells Moodle to invalidate all caches, do db upgrades if necessary,
78 install new capabilities, register event handlers, etc.
80 Example:
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
87 Local plugin capabilities
88 -------------------------
89 Each local plugin may define own capabilities. It is not recommended to define
90 capabilities belonging to other plugins here, but it should work too.
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 );
102 Local plugin language strings
103 -----------------------------
104 If customisation needs new strings it is recommended to use normal plugin
105 strings.
107 sample language file /local/nicehack/lang/en/local_nicehack.php
108 <?php
109 $string['hello'] = 'Hi {$a}';
110 $string['nicehack:nicecapability'] = 'Some capability';
113 use of the new string in code:
114 echo get_string('hello', 'local_nicehack', 'petr');
117 Local plugin admin menu items
118 -----------------------------
119 It is possible to add new items and categories to the admin_tree block.
120 I you need to define new admin setting classes put them into separate
121 file and require_once() from settings.php
123 For 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'));
130 Or if you want a new standard settings page for the plugin, inside the local
131 plugins category:
132 <?php
133 defined('MOODLE_INTERNAL') || die;
135 if ($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);
139     $settings->add(new admin_setting_configtext('local_thisplugin/option',
140         'Option', 'Information about this option', 100, PARAM_INT));
143 Local plugin event handlers
144 ---------------------------
145 Events are intended primarily for communication "core --> plugins".
146 (It should not be use in opposite direction!)
147 In theory it could be also used for "plugin --> plugin" communication too.
148 The list of core events is documented in lib/db/events.php
150 sample files
151 /local/nicehack/db/events.php
152 $handlers = array (
153     'user_deleted' => array (
154          'handlerfile'      => '/local/nicehack/lib.php',
155          'handlerfunction'  => 'nicehack_userdeleted_handler',
156          'schedule'         => 'instant'
157      ),
158 );
160 NOTE: events are not yet fully implemented in current Moodle 2.0dev.
163 Local plugin database tables
164 ----------------------------
165 XMLDB editors is the recommended tool. Please note that modification
166 of core table structure is highly discouraged.
168 If you really really really need to modify core tables you might want to do
169 that in install.php and later upgrade.php
171 Note: it is forbidden to manually modify the DB structure, without corresponding
172       changes in install.xml files.
174 List 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
181 Local plugin web services
182 -------------------------
183 During plugin installation or upgrade, the web service definitions are read
184 from /local/nicehack/db/services.php and are automatically installed/updated in Moodle.
186 sample 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 );
205 You will need to write the /local/nicehack/externallib.php - external functions
206 description and code. See some examples from the core files (/user/externallib.php,
207 /group/externallib.php...).
209 Local plugin navigation hooks
210 -----------------------------
211 There are two functions that your plugin can define that allow it to extend the main
212 navigation and the settings navigation.
213 These two functions both need to be defined within /local/nicehack/lib.php.
215 sample code
216 <?php
217 function local_nicehack_extend_navigation(global_navigation $nav) {
218     // $nav is the global navigation instance.
219     // Here you can add to and manipulate the navigation structure as you like.
220     // This callback was introduced in 2.0 as nicehack_extends_navigation(global_navigation $nav)
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
224 function local_nicehack_extend_settings_navigation(settings_navigation $nav, context $context) {
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.
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')
232 Other local customisation files
233 ===============================
235 Customised site defaults
236 ------------------------
237 Different default site settings can be stored in file /local/defaults.php.
238 These new defaults are used during installation, upgrade and later are
239 displayed as default values in admin settings. This means that the content
240 of the defaults files is usually updated BEFORE installation or upgrade.
242 These customised defaults are useful especially when using CLI tools
243 for installation and upgrade.
245 Sample /local/defaults.php file content:
246 <?php
247 $defaults['moodle']['forcelogin'] = 1;  // new default for $CFG->forcelogin
248 $defaults['scorm']['maxgrade'] = 20;    // default for get_config('scorm', 'maxgrade')
249 $defaults['moodlecourse']['numsections'] = 11;
250 $defaults['moodle']['hiddenuserfields'] = array('city', 'country');
252 First bracket contains string from column plugin of config_plugins table.
253 Second bracket is the name of setting. In the admin settings UI the plugin and
254 name of setting is separated by "|".
256 The values usually correspond to the raw string in config table, with the exception
257 of comma separated lists that are usually entered as real arrays.
259 Please note that not all settings are converted to admin_tree,
260 they are mostly intended to be set directly in config.php.
263 2.0 pre-upgrade script
264 ----------------------
265 You an use /local/upgrade_pre20.php script for any code that needs to
266 be executed before the main upgrade to 2.0. Most probably this will
267 be used for undoing of old hacks that would otherwise break normal
268 2.0 upgrade.
270 This file is just included directly, there does not need to be any
271 function inside. If the execution stops the script is executed again
272 during the next upgrade. The first execution of lib/db/upgrade.php
273 increments the version number and the pre upgrade script is not
274 executed any more.
278 1.9.x upgrade notes
279 ===================
280 1.9.x contains basic support for local hacks placed directly into
281 /local/ directory. This old local API was completely removed and can
282 not be used any more in 2.0. All old customisations need to be
283 migrated to new local plugins before running of the 2.0 upgrade script.
287 Other site customisation outside of "/local/" directory
288 =======================================================
290 Local language pack modifications
291 ---------------------------------
292 Moodle supports other type of local customisation of standard language
293 packs. If you want to create your own language pack based on another
294 language create new dataroot directory with "_local" suffix, for example
295 following file with content changes string "Login" to "Sign in":
296 moodledata/lang/en_local
297 <?php
298   $string['login'] = 'Sign in';
300 See also http://docs.moodle.org/en/Language_editing
303 Custom script injection
304 -----------------------
305 Very old customisation option that allows you to modify scripts by injecting
306 code right after the require 'config.php' call.
308 This setting is enabled by manually setting $CFG->customscripts variable
309 in config.php script. The value is expected to be full path to directory
310 with the same structure as dirroot. Please note this hack only affects
311 files that actually include the config.php!
313 Examples:
314 * disable one specific moodle page without code modification
315 * alter page parameters on the fly