[Summary view] [Print] [Text view]

   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  
  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.
  29  
  30  See also http://docs.moodle.org/dev/Local_customisation for more
  31  information.
  32  
  33  
  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/.
  38  
  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
  45  
  46  
  47  
  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
  57  
  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
  71  
  72  
  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.
  79  
  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
  85  
  86  
  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.
  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  );
 100  
 101  
 102  Local plugin language strings
 103  -----------------------------
 104  If customisation needs new strings it is recommended to use normal plugin
 105  strings.
 106  
 107  sample language file /local/nicehack/lang/en/local_nicehack.php
 108  <?php
 109  $string['hello'] = 'Hi {$a}';
 110  $string['nicehack:nicecapability'] = 'Some capability';
 111  
 112  
 113  use of the new string in code:
 114  echo get_string('hello', 'local_nicehack', 'petr');
 115  
 116  
 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
 122  
 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'));
 129  
 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;
 134  
 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);
 138  
 139      $settings->add(new admin_setting_configtext('local_thisplugin/option',
 140          'Option', 'Information about this option', 100, PARAM_INT));
 141  }
 142  
 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
 149  
 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  );
 159  
 160  NOTE: events are not yet fully implemented in current Moodle 2.0dev.
 161  
 162  
 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.
 167  
 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
 170  
 171  Note: it is forbidden to manually modify the DB structure, without corresponding
 172        changes in install.xml files.
 173  
 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
 179  
 180  
 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.
 185  
 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  );
 203  
 204  
 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...).
 208  
 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.
 214  
 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
 223  }
 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')
 230  }
 231  
 232  Other local customisation files
 233  ===============================
 234  
 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.
 241  
 242  These customised defaults are useful especially when using CLI tools
 243  for installation and upgrade.
 244  
 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');
 251  
 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 "|".
 255  
 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.
 258  
 259  Please note that not all settings are converted to admin_tree,
 260  they are mostly intended to be set directly in config.php.
 261  
 262  
 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.
 269  
 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.
 275  
 276  
 277  
 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.
 284  
 285  
 286  
 287  Other site customisation outside of "/local/" directory
 288  =======================================================
 289  
 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';
 299  
 300  See also http://docs.moodle.org/en/Language_editing
 301  
 302  
 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.
 307  
 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!
 312  
 313  Examples:
 314  * disable one specific moodle page without code modification
 315  * alter page parameters on the fly