MDL-17376 towards production ready local customisations - docs update
This commit is contained in:
Petr Skoda
+86
-36
@@ -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
|
||||
-------------------
|
||||
Each plugin may define own capabilities. It is not recommended to define
|
||||
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 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
|
||||
Reference in New Issue
Block a user