b4cb65185d97ccbe7e652106fa7d54e367170b19
[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. 
28 Wherever possible, customisations should be written using one of the
29 standard plug-in points like modules, blocks, auth plugins, themes, etc.
31 See also http://docs.moodle.org/en/Development:Local_customisation for more
32 information.
35 Directory structure
36 -------------------
37 This directory has standard plugin structure. All standard plugin features
38 are supported. There may be some extra files with special meaning in /local/.
40 Sample /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
48 Custom capabilities
49 -------------------
50 Each plugin may define own capabilities. It is not recommended to define
51 capabilities belonging to other plugins here, but it should work too.
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 ?>
64 Custom language strings
65 -----------------------
66 If customisation needs new strings it is recommended to use normal plugin
67 strings.
69 sample language file /local/nicehack/lang/en_utf8.php
70 <?php
71 $string['hello'] = 'Hi $a';
72 $string['nicehack:nicecapability'] = 'Some capability';
73 ?>
75 use of the new string in code
76 echo get_string('hello', 'local_nicehack', 'petr');
79 Custom admin menu items
80 ----------------------
81 It is possible to add new items and categories to the admin_tree block.
82 I you need to define new admin setting classes put them into separate
83 file and require_once() from settings.php
85 For 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 ?>
94 Custom event handlers
95 ---------------------
96 Events intended primarily for communication "core --> plugins". (It should not
97 be use in opposite direction!) In theory it could be also used for 
98 "plugin --> plugin" communication too. The list of core events is documented
99 in lib/db/events.php
101 sample 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 );
111 NOTE: events are not yet fulyl implemented in current Moodle 2.0dev.
114 Custom db tables
115 ----------------
116 XMLDB editors is the recommended tool. Please note that modification
117 of core table structure is highly discouraged.
119 If you really really really need to modify core tables you might want to do
120 that in install.php and later upgrade.php
122 List 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
130 Customised site defaults
131 ------------------------
132 Different default site settings can be stored in file /local/defaults.php.
133 These new defaults are used during installation, upgrade and later are
134 displayed as default values in admin settings.
136 Sample /local/defaults.php file content:
137 <?php
138 $defaults['moodle']['forcelogin'] = 1;
139 $defaults['scorm']['maxgrade'] = 20;
140 $defaults['moodlecourse']['numsections'] = 11;
141 ?>
143 First bracket contains string from column plugin of config_plugins table.
144 Second bracket is the name of setting. In the admin settings UI the plugin and
145 name of setting is separated by "|".
147 Please note that not all settings are converted to admin_tree yet.
150 1.9.x upgrade notes
151 -------------------
152 1.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.
155 You an use /local/upgrade_pre20.php script for any code that needs to
156 be executed before the main upgrade to 2.0.
160 Other customisation information
161 ===============================
163 Local language pack modifications
164 ---------------------------------
165 Moodle supports other type of local customisation of standard language
166 packs. If you want to create your own language pack based on another
167 language create new dataroot directory with "_local" suffix, for example
168 following file with content changes string "Login" to "Sign in":
169 moodledata/lang/en_utf8_local
170 <?php
171   $string['login'] = 'Sign in';
172 ?>
174 See also http://docs.moodle.org/en/Language_editing