MDL-16438 centralise information about plugins to avoid duplication, includes local...
[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==============================
26This directory is the recommended place for local customisations.
27
28Wherever possible, customisations should be written using one of the
29standard plug-in points like modules, blocks, auth plugins, themes, etc.
30
31See also http://docs.moodle.org/en/Development:Local_customisation for more
32information.
33
34
35Directory structure
36-------------------
37This directory has standard plugin structure. All standard plugin features
38are supported. There may be some extra files with special meaning in /local/.
39
40Sample /local/ directory listing:
41/local/nicehack/ - first customisation plugin
42/local/otherhack/ - other customisation plugin
43/local/upgrade_pre20.php - one time upgrade and migration script which is
44 executed before main 2.0 upgrade
45/local/defaults.php - custom admin setting defaults
46
47
48Custom capabilities
49-------------------
50Each plugin may define own capabilities. It is not recommended to define
51capabilities belonging to other plugins here, but it should work too.
52
53/local/nicehack/access.php content
54<?php
55$local_nicehack_capabilities = array(
56 'local/nicehack:nicecapability' => array(
57 'captype' => 'read',
58 'contextlevel' => CONTEXT_SYSTEM,
59 ),
60);
61?>
62
63
64Custom language strings
65-----------------------
66If customisation needs new strings it is recommended to use normal plugin
67strings.
68
69sample language file /local/nicehack/lang/en_utf8.php
70<?php
71$string['hello'] = 'Hi $a';
72$string['nicehack:nicecapability'] = 'Some capability';
73?>
74
75use of the new string in code
76echo get_string('hello', 'local_nicehack', 'petr');
77
78
79Custom admin menu items
80----------------------
81It is possible to add new items and categories to the admin_tree block.
82I you need to define new admin setting classes put them into separate
83file and require_once() from settings.php
84
85For example if you want to add new external page use following
86/local/nicehack/settings.php
87<?php
88$ADMIN->add('root', new admin_category('tweaks', 'Custom tweaks'));
89$ADMIN->add('tweaks', new admin_externalpage('nicehackery', 'Tweak something',
90 $CFG->wwwroot.'/local/nicehack/setuppage.php'));
91?>
92
93
94Custom event handlers
95---------------------
96Events intended primarily for communication "core --> plugins". (It should not
97be use in opposite direction!) In theory it could be also used for
98"plugin --> plugin" communication too. The list of core events is documented
99in lib/db/events.php
100
101sample files
102/local/nicehack/db/events.php
103$handlers = array (
104 'user_deleted' => array (
105 'handlerfile' => '/local/nicehack/lib.php',
106 'handlerfunction' => 'nicehack_userdeleted_handler',
107 'schedule' => 'instant'
108 ),
109);
110
111NOTE: events are not yet fulyl implemented in current Moodle 2.0dev.
112
113
114Custom db tables
115----------------
116XMLDB editors is the recommended tool. Please note that modification
117of core table structure is highly discouraged.
118
119If you really really really need to modify core tables you might want to do
120that in install.php and later upgrade.php
121
122List of upgrade related files:
123/local/nicehack/db/install.xml - contains XML definition of new tables
124/local/nicehack/db/install.php - executed after db creation, may be also used
125 for general install code
126/local/nicehack/db/upgrade.php - executed when version changes
127/local/nicehack/version.php - version specification file
128
129
130Customised site defaults
131------------------------
132Different default site settings can be stored in file /local/defaults.php.
133These new defaults are used during installation, upgrade and later are
134displayed as default values in admin settings.
135
136Sample /local/defaults.php file content:
137<?php
138$defaults['moodle']['forcelogin'] = 1;
139$defaults['scorm']['maxgrade'] = 20;
140$defaults['moodlecourse']['numsections'] = 11;
141?>
142
143First bracket contains string from column plugin of config_plugins table.
144Second bracket is the name of setting. In the admin settings UI the plugin and
145name of setting is separated by "|".
146
147Please note that not all settings are converted to admin_tree yet.
148
149
1501.9.x upgrade notes
151-------------------
1521.9.x contains basic support for local hacks placed directly into
153/local/ directory. This old local API is not supported any more in 2.0.
154
155You an use /local/upgrade_pre20.php script for any code that needs to
156be executed before the main upgrade to 2.0.
157
158
159
160Other customisation information
161===============================
162
163Local language pack modifications
164---------------------------------
165Moodle supports other type of local customisation of standard language
166packs. If you want to create your own language pack based on another
167language create new dataroot directory with "_local" suffix, for example
168following file with content changes string "Login" to "Sign in":
169moodledata/lang/en_utf8_local
170<?php
171 $string['login'] = 'Sign in';
172?>
173
174See also http://docs.moodle.org/en/Language_editing