MDL-17376 towards production ready local customisations - docs update
[moodle.git] / local / readme.txt
index 294e061..6ad6809 100644 (file)
@@ -24,9 +24,8 @@
 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.
+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.
@@ -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
-                           executed before main 2.0 upgrade
+                           executed before main 2.0 upgrade starts
 /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
@@ -58,25 +83,24 @@ $local_nicehack_capabilities = array(
         'contextlevel' => CONTEXT_SYSTEM,
     ),
 );
-?>
 
 
-Custom language strings
+Local plugin language strings
 -----------------------
 If customisation needs new strings it is recommended to use normal plugin
 strings.
 
 sample language file /local/nicehack/lang/en/local_nicehack.php
 <?php
-$string['hello'] = 'Hi $a';
+$string['hello'] = 'Hi {$a}';
 $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');
 
 
-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
@@ -88,15 +112,14 @@ 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'));
-?>
 
 
-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
@@ -108,10 +131,10 @@ $handlers = array (
      ),
 );
 
-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.
@@ -119,53 +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
 
+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
-/local/nicehack/version.php    - version specification file
 
 
-Version.php example
--------------------
-/local/nicehack/version.php
-
-$plugin->version  = 2010022400;   // The (date) version of this plugin
-$plugin->requires = 2010021900;  // Requires this Moodle version
 
+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
-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
-$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['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 "|".
 
-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
-/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
-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
@@ -177,6 +213,20 @@ following file with content changes string "Login" to "Sign in":
 moodledata/lang/en_local
 <?php
   $string['login'] = 'Sign in';
-?>
 
 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