[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_extends_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 the now preferred local_nicehack_extends_navigation(global_navigation $nav).
 222  }
 223  function local_nicehack_extends_settings_navigation(settings_navigation $nav, context $context) {
 224      // $nav is the settings navigation instance.
 225      // $context is the context the settings have been loaded for (settings is context specific)
 226      // Here you can add to and manipulate the settings structure as you like.
 227      // This callback was introduced in 2.3
 228  }
 229  
 230  Other local customisation files
 231  ===============================
 232  
 233  Customised site defaults
 234  ------------------------
 235  Different default site settings can be stored in file /local/defaults.php.
 236  These new defaults are used during installation, upgrade and later are
 237  displayed as default values in admin settings. This means that the content
 238  of the defaults files is usually updated BEFORE installation or upgrade.
 239  
 240  These customised defaults are useful especially when using CLI tools
 241  for installation and upgrade.
 242  
 243  Sample /local/defaults.php file content:
 244  <?php
 245  $defaults['moodle']['forcelogin'] = 1;  // new default for $CFG->forcelogin
 246  $defaults['scorm']['maxgrade'] = 20;    // default for get_config('scorm', 'maxgrade')
 247  $defaults['moodlecourse']['numsections'] = 11;
 248  $defaults['moodle']['hiddenuserfields'] = array('city', 'country');
 249  
 250  First bracket contains string from column plugin of config_plugins table.
 251  Second bracket is the name of setting. In the admin settings UI the plugin and
 252  name of setting is separated by "|".
 253  
 254  The values usually correspond to the raw string in config table, with the exception
 255  of comma separated lists that are usually entered as real arrays.
 256  
 257  Please note that not all settings are converted to admin_tree,
 258  they are mostly intended to be set directly in config.php.
 259  
 260  
 261  2.0 pre-upgrade script
 262  ----------------------
 263  You an use /local/upgrade_pre20.php script for any code that needs to
 264  be executed before the main upgrade to 2.0. Most probably this will
 265  be used for undoing of old hacks that would otherwise break normal
 266  2.0 upgrade.
 267  
 268  This file is just included directly, there does not need to be any
 269  function inside. If the execution stops the script is executed again
 270  during the next upgrade. The first execution of lib/db/upgrade.php
 271  increments the version number and the pre upgrade script is not
 272  executed any more.
 273  
 274  
 275  
 276  1.9.x upgrade notes
 277  ===================
 278  1.9.x contains basic support for local hacks placed directly into
 279  /local/ directory. This old local API was completely removed and can
 280  not be used any more in 2.0. All old customisations need to be
 281  migrated to new local plugins before running of the 2.0 upgrade script.
 282  
 283  
 284  
 285  Other site customisation outside of "/local/" directory
 286  =======================================================
 287  
 288  Local language pack modifications
 289  ---------------------------------
 290  Moodle supports other type of local customisation of standard language
 291  packs. If you want to create your own language pack based on another
 292  language create new dataroot directory with "_local" suffix, for example
 293  following file with content changes string "Login" to "Sign in":
 294  moodledata/lang/en_local
 295  <?php
 296    $string['login'] = 'Sign in';
 297  
 298  See also http://docs.moodle.org/en/Language_editing
 299  
 300  
 301  Custom script injection
 302  -----------------------
 303  Very old customisation option that allows you to modify scripts by injecting
 304  code right after the require 'config.php' call.
 305  
 306  This setting is enabled by manually setting $CFG->customscripts variable
 307  in config.php script. The value is expected to be full path to directory
 308  with the same structure as dirroot. Please note this hack only affects
 309  files that actually include the config.php!
 310  
 311  Examples:
 312  * disable one specific moodle page without code modification
 313  * alter page parameters on the fly