MDL-17376 towards production ready local customisations - docs update
[moodle.git] / local / readme.txt
index b4cb651..6ad6809 100644 (file)
 
 Local customisations directory
 ==============================
 
 Local customisations directory
 ==============================
-This directory is the recommended place for local customisations. 
-
-Wherever possible, customisations should be written using one of the
-standard plug-in points like modules, blocks, auth plugins, themes, etc.
+This directory is the recommended place for local customisations.
+Wherever possible, customisations should be written using one
+of the standard plug-in points like modules, blocks, auth plugins, themes, etc.
 
 See also http://docs.moodle.org/en/Development:Local_customisation for more
 information.
 
 See also http://docs.moodle.org/en/Development:Local_customisation for more
 information.
@@ -41,13 +40,39 @@ Sample /local/ directory listing:
 /local/nicehack/         - first customisation plugin
 /local/otherhack/        - other customisation plugin
 /local/upgrade_pre20.php - one time upgrade and migration script which is
 /local/nicehack/         - first customisation plugin
 /local/otherhack/        - other customisation plugin
 /local/upgrade_pre20.php - one time upgrade and migration script which is
-                           executed before main 2.0 upgrade
+                           executed before main 2.0 upgrade starts
 /local/defaults.php      - custom admin setting defaults
 
 
 /local/defaults.php      - custom admin setting defaults
 
 
-Custom capabilities
+
+Local plugins
+===============================
+Local plugins are used in cases when no standard plugin fits, examples are:
+* event consumers communicating with external systems
+* custom definitions of web services and external functions
+* applications that extend moodle at the system level (hub server, amos server, etc.)
+* new database tables used in core hacks (discouraged)
+* new capability definitions used in core hacks
+* custom admin settings
+
+
+Local plugin version specification
+-------------------
+version.php is mandatory for most of the standard plugin infrastructure.
+The version number must be incremented most plugin changes, the changed
+version tells Moodle to invalidate all caches, do db upgrades if necessary,
+install new capabilities, register event handlers, etc.
+
+Example:
+/local/nicehack/version.php
+<?php
+$plugin->version  = 2010022400;   // The (date) version of this plugin
+$plugin->requires = 2010021900;   // Requires this Moodle version
+
+
+Local plugin capabilities
 -------------------
 -------------------
-Each plugin may define own capabilities. It is not recommended to define
+Each local plugin may define own capabilities. It is not recommended to define
 capabilities belonging to other plugins here, but it should work too.
 
 /local/nicehack/access.php content
 capabilities belonging to other plugins here, but it should work too.
 
 /local/nicehack/access.php content
@@ -58,25 +83,24 @@ $local_nicehack_capabilities = array(
         'contextlevel' => CONTEXT_SYSTEM,
     ),
 );
         'contextlevel' => CONTEXT_SYSTEM,
     ),
 );
-?>
 
 
 
 
-Custom language strings
+Local plugin language strings
 -----------------------
 If customisation needs new strings it is recommended to use normal plugin
 strings.
 
 -----------------------
 If customisation needs new strings it is recommended to use normal plugin
 strings.
 
-sample language file /local/nicehack/lang/en_utf8.php
+sample language file /local/nicehack/lang/en/local_nicehack.php
 <?php
 <?php
-$string['hello'] = 'Hi $a';
+$string['hello'] = 'Hi {$a}';
 $string['nicehack:nicecapability'] = 'Some capability';
 $string['nicehack:nicecapability'] = 'Some capability';
-?>
 
 
-use of the new string in code
+
+use of the new string in code:
 echo get_string('hello', 'local_nicehack', 'petr');
 
 
 echo get_string('hello', 'local_nicehack', 'petr');
 
 
-Custom admin menu items
+Local plugin admin menu items
 ----------------------
 It is possible to add new items and categories to the admin_tree block.
 I you need to define new admin setting classes put them into separate
 ----------------------
 It is possible to add new items and categories to the admin_tree block.
 I you need to define new admin setting classes put them into separate
@@ -88,30 +112,29 @@ For example if you want to add new external page use following
 $ADMIN->add('root', new admin_category('tweaks', 'Custom tweaks'));
 $ADMIN->add('tweaks', new admin_externalpage('nicehackery', 'Tweak something',
             $CFG->wwwroot.'/local/nicehack/setuppage.php'));
 $ADMIN->add('root', new admin_category('tweaks', 'Custom tweaks'));
 $ADMIN->add('tweaks', new admin_externalpage('nicehackery', 'Tweak something',
             $CFG->wwwroot.'/local/nicehack/setuppage.php'));
-?>
 
 
 
 
-Custom event handlers
+Local plugin event handlers
 ---------------------
 ---------------------
-Events intended primarily for communication "core --> plugins". (It should not
-be use in opposite direction!) In theory it could be also used for 
-"plugin --> plugin" communication too. The list of core events is documented
-in lib/db/events.php
+Events are intended primarily for communication "core --> plugins".
+(It should not be use in opposite direction!)
+In theory it could be also used for "plugin --> plugin" communication too.
+The list of core events is documented in lib/db/events.php
 
 sample files
 /local/nicehack/db/events.php
 $handlers = array (
     'user_deleted' => array (
          'handlerfile'      => '/local/nicehack/lib.php',
 
 sample files
 /local/nicehack/db/events.php
 $handlers = array (
     'user_deleted' => array (
          'handlerfile'      => '/local/nicehack/lib.php',
-         'handlerfunction'  => 'nicehack_userdeleted_handler', 
+         'handlerfunction'  => 'nicehack_userdeleted_handler',
          'schedule'         => 'instant'
      ),
 );
 
          'schedule'         => 'instant'
      ),
 );
 
-NOTE: events are not yet fulyl implemented in current Moodle 2.0dev.
+NOTE: events are not yet fully implemented in current Moodle 2.0dev.
 
 
 
 
-Custom db tables
+Local plugin database tables
 ----------------
 XMLDB editors is the recommended tool. Please note that modification
 of core table structure is highly discouraged.
 ----------------
 XMLDB editors is the recommended tool. Please note that modification
 of core table structure is highly discouraged.
@@ -119,45 +142,66 @@ of core table structure is highly discouraged.
 If you really really really need to modify core tables you might want to do
 that in install.php and later upgrade.php
 
 If you really really really need to modify core tables you might want to do
 that in install.php and later upgrade.php
 
+Note: it is forbidden to manually modify the DB structure, without corresponding
+      changes in install.xml files.
+
 List of upgrade related files:
 /local/nicehack/db/install.xml - contains XML definition of new tables
 /local/nicehack/db/install.php - executed after db creation, may be also used
                                  for general install code
 /local/nicehack/db/upgrade.php - executed when version changes
 List of upgrade related files:
 /local/nicehack/db/install.xml - contains XML definition of new tables
 /local/nicehack/db/install.php - executed after db creation, may be also used
                                  for general install code
 /local/nicehack/db/upgrade.php - executed when version changes
-/local/nicehack/version.php    - version specification file
 
 
 
 
+
+Other local customisation files
+===============================
+
 Customised site defaults
 ------------------------
 Different default site settings can be stored in file /local/defaults.php.
 These new defaults are used during installation, upgrade and later are
 Customised site defaults
 ------------------------
 Different default site settings can be stored in file /local/defaults.php.
 These new defaults are used during installation, upgrade and later are
-displayed as default values in admin settings.
+displayed as default values in admin settings. This means that the content
+of the defaults files is usually updated BEFORE installation or upgrade.
+
+These customised defaults are useful especially when using CLI tools
+for installation and upgrade.
 
 Sample /local/defaults.php file content:
 <?php
 
 Sample /local/defaults.php file content:
 <?php
-$defaults['moodle']['forcelogin'] = 1;
-$defaults['scorm']['maxgrade'] = 20;
+$defaults['moodle']['forcelogin'] = 1;  // new default for $CFG->forcelogin
+$defaults['scorm']['maxgrade'] = 20;    // default for get_config('scorm', 'maxgrade')
 $defaults['moodlecourse']['numsections'] = 11;
 $defaults['moodlecourse']['numsections'] = 11;
-?>
+$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
 
 First bracket contains string from column plugin of config_plugins table.
 Second bracket is the name of setting. In the admin settings UI the plugin and
 name of setting is separated by "|".
 
 
 First bracket contains string from column plugin of config_plugins table.
 Second bracket is the name of setting. In the admin settings UI the plugin and
 name of setting is separated by "|".
 
-Please note that not all settings are converted to admin_tree yet.
+The values usually correspond to the raw string in config table, with the exception
+of comma separated lists that are usually entered as real arrays. 
+
+Please note that not all settings are converted to admin_tree,
+they are mostly intended to be set directly in config.php.
 
 
 1.9.x upgrade notes
 -------------------
 1.9.x contains basic support for local hacks placed directly into
 
 
 1.9.x upgrade notes
 -------------------
 1.9.x contains basic support for local hacks placed directly into
-/local/ directory. This old local API is not supported any more in 2.0.
+/local/ directory. This old local API was completely removed and can
+not be used any more in 2.0. All old customisations need to be
+migrated to new local plugins before running of the 2.0 upgrade script.
+
 
 
+2.0 pre-upgrade script
+-------------------
 You an use /local/upgrade_pre20.php script for any code that needs to
 You an use /local/upgrade_pre20.php script for any code that needs to
-be executed before the main upgrade to 2.0.
+be executed before the main upgrade to 2.0. Most probably this will
+be used for undoing of old hacks that would otherwise break normal
+2.0 upgrade.
 
 
 
 
 
 
-Other customisation information
+Other site customisation outside of "/local/" directory
 ===============================
 
 Local language pack modifications
 ===============================
 
 Local language pack modifications
@@ -166,9 +210,23 @@ Moodle supports other type of local customisation of standard language
 packs. If you want to create your own language pack based on another
 language create new dataroot directory with "_local" suffix, for example
 following file with content changes string "Login" to "Sign in":
 packs. If you want to create your own language pack based on another
 language create new dataroot directory with "_local" suffix, for example
 following file with content changes string "Login" to "Sign in":
-moodledata/lang/en_utf8_local
+moodledata/lang/en_local
 <?php
   $string['login'] = 'Sign in';
 <?php
   $string['login'] = 'Sign in';
-?>
 
 See also http://docs.moodle.org/en/Language_editing
 
 See also http://docs.moodle.org/en/Language_editing
+
+
+Custom script injection
+---------------------------------
+Very old customisation option that allows you to modify scripts by injecting
+code right after the require 'config.php' call.
+
+This setting is enabled by manually setting $CFG->customscripts variable
+in config.php script. The value is expected to be full path to directory
+with the same structure as dirroot. Please note this hack only affects
+files that actually include the config.php!
+
+Examples:
+* disable one specific moodle page without code modification
+* alter page parameters on the fly 
\ No newline at end of file