navigation MDL-22445 Fixed docking issue on multiple dock+undock actions
[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.
17da2e6f 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
3a915b06 69sample language file /local/nicehack/lang/en/local_nicehack.php
17da2e6f 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
6f5e0852 97be use in opposite direction!) In theory it could be also used for
17da2e6f 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',
6f5e0852 106 'handlerfunction' => 'nicehack_userdeleted_handler',
17da2e6f 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
c6eb9bc6 130Version.php example
131-------------------
132/local/nicehack/version.php
133
134$plugin->version = 2010022400; // The (date) version of this plugin
135$plugin->requires = 2010021900; // Requires this Moodle version
136
137
17da2e6f 138Customised site defaults
139------------------------
140Different default site settings can be stored in file /local/defaults.php.
141These new defaults are used during installation, upgrade and later are
142displayed as default values in admin settings.
143
144Sample /local/defaults.php file content:
145<?php
146$defaults['moodle']['forcelogin'] = 1;
147$defaults['scorm']['maxgrade'] = 20;
148$defaults['moodlecourse']['numsections'] = 11;
149?>
150
151First bracket contains string from column plugin of config_plugins table.
152Second bracket is the name of setting. In the admin settings UI the plugin and
153name of setting is separated by "|".
154
155Please note that not all settings are converted to admin_tree yet.
156
157
1581.9.x upgrade notes
159-------------------
1601.9.x contains basic support for local hacks placed directly into
161/local/ directory. This old local API is not supported any more in 2.0.
162
163You an use /local/upgrade_pre20.php script for any code that needs to
164be executed before the main upgrade to 2.0.
165
166
167
168Other customisation information
169===============================
170
171Local language pack modifications
172---------------------------------
173Moodle supports other type of local customisation of standard language
174packs. If you want to create your own language pack based on another
175language create new dataroot directory with "_local" suffix, for example
176following file with content changes string "Login" to "Sign in":
3a915b06 177moodledata/lang/en_local
17da2e6f 178<?php
179 $string['login'] = 'Sign in';
180?>
181
182See also http://docs.moodle.org/en/Language_editing