Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Local customisation.

Development:Local customisation: Difference between revisions

From MoodleDocs
(→‎See also: readme link)
 
(41 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Disclaimer ==
{{Infobox Project
|name = Local customisations
|state = Implemented
|tracker = MDL-17376, MDL-16438
|discussion = http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]], some parts were originally proposed and implemented in 1.9 by Penny Leach
}}
{{Moodle 2.0}}


Some of these entries are things that Penny has patches for and has not yet committed, and are under discussion. The meta bug for all these items is here:  http://tracker.moodle.org/browse/MDL-17376
The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.


== General customisations ==
== Custom /local/ plugins ==


Moodle has been designed with extensibility in mind. There are many plug-in points available throughout Moodle to allow developers add new functionality to Moodle without modifying core code.
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
* extending the navigation block with custom menus [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095]


See the [[Developer_documentation#Make_a_new_plugin|make a new plugin section of the Developer documentation page]] for the different plugin types available, and documentation on how to develop for them.
=== Standard plugin features: ===
* /local/xxx/version.php - version of script (must be incremented after changes)
* /local/xxx/db/install.xml - executed during install (new version.php found)
* /local/xxx/db/install.php - executed right after install.xml
* /local/xxx/db/uninstall.php - executed during uninstallation
* /local/xxx/db/upgrade.php - executed after version.php change
* /local/xxx/db/access.php - definition of capabilities
* /local/xxx/db/events.php - event handlers and subscripts
* /local/xxx/db/messages.php - messaging registration
* /local/xxx/db/external.php - web services and external functions descriptions
* /local/xxx/lang/en/local_pluginname.php - language file


== local/ folder for 'hacky' customisations ==
The ''xxx'' is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.


Sometimes it is not possible to use the available plug-in points to make your change. In situations like this then the local folder is for you. The idea is that instead of scattering your changes throughout the code base, you put them all in a folder called 'local'. Using this folder means you won't have to deal with merging problems when you upgrade the rest of your Moodle installation.
=== List of differences from normal plugins: ===
 
* always executed last during install/upgrade - guaranteed by order of plugins in <code>get_plugin_types()</code>
The local folder has some of the plug-in points available which are available to other modules. Perhaps most useful the local/db/ folder can be used to make database schema changes and custom role permissions.
* are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
 
* can add admin settings to any settings page - loaded last when constructing admin tree
However, using the local folder should be absolutely the last resort. Long term, you will almost certainly find it easier to maintain your changes if you can package them up as one of the standard types of plugins.
* do not need to have any UI - other plugins are usually visible somewhere
 
* some extra hooks (not implemented yet)
=== Local database changes and version ===
 
If you need to make local database customisations that are not easily encapsulated by a block or module, Moodle does support the use of a local db upgrade script, and local version number.
 
This is almost exactly the same as every other db/upgrade.php and version.php except for the following points:
 
==== local/version.php ====
 
local/version.php must look like:
 
<code php>
$local_version = 2008121700;
</code>
 
==== local/db/install.xml ====
 
Local/ has no install.xml - only an upgrade.php.  This is because often the changes that you want to make are not full tables, but just extra columns, and a local install.xml makes less sense than just upgrade.php.
 
If you would like to create tables using using an install.xml this can be achieved by putting something like that this in your upgrade.php file:


== /local/xxx/db/messages.php ==
Example File Structure:
<code php>
<code php>
$result = install_from_xmldb_file(dirname(__FILE__).'/install.xml');
<?php
</code>
 
==== local/db/upgrade.php ====


local/db/upgrade.php must look like:
/**
* Defines message providers (types of messages being sent)
*
* @package mod-forum
* @copyright  1999 onwards  Martin Dougiamas  http://moodle.com
* @license  http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/


<code php>
$messageproviders = array (
function xmldb_local_upgrade($oldversion) {
    global $CFG, $db;


     $result = true;
/// Ordinary single forum posts
     'posts' => array (
    )


    if ($result && $oldversion < 2008121700) {
);
        $result = $result && create_table($table);
    }
    return $result;
}
</code>
</code>


=== Local post-installation data insertion ===
== Other /local/ customisation files==  


In discussion - see http://tracker.moodle.org/browse/MDL-17440
===Customised site defaults===


=== Local capabilities ===
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. This means that the content
of the defaults files is usually updated BEFORE installation or upgrade.


Just like core and modules, Moodle supports the use of a '''db/access.php''' inside local/ to define local capabilities.
These customised defaults are useful especially when using CLI tools
 
for installation and upgrade.
The formatting is exactly the same as the other db/access.php scripts  - an array keyed by capability name, containing arrays of capability data, like so:


Sample /local/defaults.php file content:
<code php>
<code php>
$local_capabilities = array(
<?php
    'moodle/local:capability' => array(
$defaults['moodle']['forcelogin'] = 1;  // new default for $CFG->forcelogin
        'captype'     => 'write',
$defaults['scorm']['maxgrade'] = 20;    // default for get_config('scorm', 'maxgrade')
        'contextlevel' => CONTEXT_SYSTEM,
$defaults['moodlecourse']['numsections'] = 11;
        'riskbitmask' => RISK_SPAM,
$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
    ),
</code>
</code>
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 "|".


Note that for all local capabilities you add, you'll need to add language strings. Moodle will expect to find them in '''local/lang/en_utf8/local.php''' (eg for English) with a key (following the above example) of local:capability, like so:
The values usually correspond to the raw string in config table, with the exception
<code php>
of comma separated lists that are usually entered as real arrays.
$string['local:capability'] =  'The language-string';
</code>
 
=== Local event subscriptions ===
 
''' Pending commit '''
 
It is often very helpful to be able to write custom code that subscribes to normal events that Moodle throws.  It's also handy to be able to throw and catch your own custom events, as the Event API provides a very handy mechanism to do signal handling.
 
Local event handlers get registered at install/upgrade time just as the event handlers for modules do.  To trigger an update when you add a new event handler, you must bump the local version number.
 
Event handlers must be defined in an array, keyed by event name, with each entry in the array information about the handler, like so:
 
<code php>
    $handlers = array(
        'some_core_event'    => array(            // eg 'user_created'
            'handlerfile'    => '/local/lib.php', // example
            'handlerfunction' => 'local_user_create_handler',
            'schedule'        => 'cron'
        )
    );
</code>
 
=== Local admin menu items and settings ===
 
You can add extra configuration items to Moodle by creating a file, local/settings.php which accesses the $ADMIN variable directly and adds new items to it.  This will make them appear in the site administration block on the homepage, and create the config options that administrators can change.  You can also add whole new custom config pages (admin_externalpage).  For example:
 
<code php>
 
$ADMIN->add('root', new admin_category($name, $title));
$ADMIN->add('foo', new admin_externalpage($name, $title, $url, $cap));
 
</code>
 
=== Local backup and restore hooks ===
 
In discussion - see http://tracker.moodle.org/browse/MDL-17444
 
=== Local course deletion hook ===
 
This is due to be removed, and replaced with an event.
 
Previously, when you emptied ('''not deleted''') a course, the notify_local_course_delete method was called, which looked for a local_delete_course method in local/lib.php.  The naming of this is a little ambiguous because the course is being emptied, not deleted.
 
Going forwards, we aim to have two events - course_emptied and course_deleted.  Support for the local_delete_course method will be removed.
 
See http://tracker.moodle.org/browse/MDL-17445 for more info.
 
=== Local my moodle overrides ===
 
('''pending commit''')
 
By default, the My Moodle page shows a course overview in the center column.  Some sites might want to replace that with some custom code, or even just some static content.  This is very easily accomplished by:
 
* Creating a local/lib.php
* Putting a function in there, called local_my_moodle.


This function will be called '''instead of'' (rather than in addition to), the default center column.
Please note that not all settings are converted to admin_tree,
they are mostly intended to be set directly in config.php.


=== Local stickyblocks targets ===
=== 2.0 pre-upgrade script===


('''pending commit''')
You can use /local/upgrade_pre20.php script for any code that needs to
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.


In the case where you're developing a heavily customised site, it might happen that you develop a pagetype that has the ability for people to add blocks to. In this case, you might want to also make it stickyblock enabled.
This file is just included directly, there does not need to be any
function inside. If the execution stops the script is executed again
during the next upgrade. The first execution of lib/db/upgrade.php
increments the version number and the pre upgrade script is not
executed any more.


This is easily achieved by:
== Customisations outside of /local/ directory==
 
* Create local/lib.php
* Create a method in there called local_get_sticky_pagetypes that returns an array just like the $pagetypes array at the top of admin/stickyblocks.php.
 
For example:
 
<code php>


function local_get_sticky_pagetypes() {
=== Forced settings===  
    return array(
        'custom_pagetype' => array(
            'id' => 'custom_pagetype',
            'lib' => '/local/lib.php',
            'name' => get_string('custom_pagetype', 'local')
        )
    );
}


</code>
Sometimes it is useful to force some settings and prevent any changes of these settings via the standard admin UI. It is possible to hardcode these settings in config.php.


You then must create a page that extends page_base.  Don't forget that if your pagetype is stickyblock enabled, it needs to take this into account in some of its methods. For example:
In case of course settings it is very simply, the values are assigned directly to $CFG properties. In case of plugins the values are specified in a multidimensional array in $CFG->force_plugin_settings.


Sample code in config.php
<code php>
<code php>
 
$CFG->allowobjectembed = 0;
class custom_pagetype extends page_base {
$CFG->forced_plugin_settings = array('page'=>array('displayoptions'=>5, 'requiremodintro'=>1), 'folder'=>'requiremodintro'=>1);
 
    // normal page type class
 
    function url_get_path() {
        global $CFG;
        if (defined('ADMIN_STICKYBLOCKS')) { // admin is editing stickyblocks, not a normal page
            return $CFG->wwwroot . '/admin/stickyblocks.php';
        }
        return '';
    }
 
    function url_get_parameters() {
        global $CFG;
        if (defined('ADMIN_STICKYBLOCKS')) {
            return array('pt' => 'custom_pagetype');
        }
    }
}
</code>
</code>


and map it with page_map_class:
=== Local language customisations===


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":
moodledata/lang/en_local
<code php>
<code php>
page_map_class('custom_pagetype', 'custom_pagetype');
<?php
  $string['login'] = 'Sign in';
</code>
</code>
See also https://docs.moodle.org/en/Language_editing


=== Local user profile view hook ===
=== Custom script injection===  
 
('''pending commit''')


Sometimes, it may be desirable to do something like add extra buttons to the bottom of the user's profile page - if you've developed some custom code to perform extra actions on a user, for example.  This is very easy to do.
Very old customisation option that allows you to modify scripts by injecting
code right after the require 'config.php' call.


* Create local/lib.php
This setting is enabled by manually setting $CFG->customscripts variable
* Create a function in there, local_user_view.
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!


<code php>
; Examples:
* disable one specific moodle page without code modification
* alter page parameters on the fly


function local_user_view($user, $course) {
=== Direct code modifications===
This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).


    // capability check
=== Direct database modifications===
Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.


    // extra stuff
== Local customisations in previous versions ==
Previous versions include only partial support for customisations in /local/ directory.


}
=== List of local customisations in 1.9.x: ===
* /local/cron.php - custom cron jobs
* /local/settings.php - custom admin settings
* /local/db/upgrade.php - general modifications
* /local/lang/* - custom strings
* /local/lib.php - local_delete_course()


</code>
=== Migration from old 1.9.x /local/: ===
 
=== Local language strings ===
 
Moodle already supports local overriding of any language strings, or the creation of new strings. Just create a folder lang/XX_utf8_local where XX is a language code. Any language files you put in there will be used before the standard files. So, for example, can can create a file lang/en_utf8_local/moodle.php containing
$string['login'] = 'Sign in';
and that will change the string 'Login' to 'Sign in'. (See [[Language editing]] for another way to achieve this.)
 
This mechanism can also be used to create completely new language files. For example, suppose you have created some code in local/myfeature.php that needs some language strings. You can put those strings in the file lang/en_utf8_local/local_myfeature.php, and then access then using get_string('mystring', 'local_myfeature'). (Note that you do not have to call the file local_myfeature.php, you can call it anything you like, however, the convention of calling lang files for local/ code local_somthing is recommended.)
 
In addition, there is one other mechanism that is available. Strings from the 'local' language file (for example get_string('mystring', 'local') will be found if the string is defined in the file local/lang/en_utf8/local.php. Since the lang file 'local' is used for a lot of things like capability names, you can use this file for things like that.
 
=== Local cron ===
 
If the file exists, local/cron.php is included by admin/cron.php every time cron is run.
 
==See also==
 
*[http://cvs.moodle.org/moodle/lib/locallib.php?view=markup CVS:moodle/lib/locallib.php]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=86903 Local Customisations] forum discussion
* http://cvs.moodle.org/moodle/local/readme.txt?revision=1.1&view=markup
 
=Local plugins in 2.0 proposal=
'''Author:''' [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
 
'''Tracker issues:'''  MDL-16438
 
'''Moodle.org discussion:''' http://moodle.org/mod/forum/discuss.php?d=126017
 
The information above is already a bit obsolete due to recent major refactoring of install and upgrade scripts. Instead of hardcoding ''local'' exceptions all over the code base we can simply add new plugin type ''local'' and finish implementation of events notifications. Implementation above is never ending battle of keeping local/* hacks in sync with Moodle development which is imo not optimal solution.
 
 
Benefits:
* local plugins would be far less hacky
* absolutely no cost of ''local'' maintenance in core - it is just another general plugin
* much easier to implement
* more concurrent plugin modifications possible, not just one huge local hack
* this would motivate us to finally finish events
 
 
'''Migration from old local/*'''
* <code>local/*</code> needs to be copied to new directory
* <code>local/*</code> needs to be copied to new directory
* <code>local/xxxx/db/install.php</code> is intended for first installation, originally everything was in upgrade.php
* <code>local/xxxx/db/install.php</code> is intended for first installation, originally everything was in upgrade.php
Line 261: Line 170:
* upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade
* upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade


==See also==


List of differences from normal plugins:
* [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Extending navigation block]
* always executed last during install/upgrade - guaranteed by order of plugins in <code>get_plugin_types()</code>
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=86903 Local Customisations] forum discussion
* are expected to use event handlers - event are intended for communication core-->plugins only, local plugins the best candidates for event handlers
* http://cvs.moodle.org/moodle/local/readme.txt?view=markup
* can add admin settings to any page - loaded last when constructing admin tree
* [[Local customisation (Moodle 1.9)]]
* in exceptional cases modify other db tables - not supported officially, do it at your own risk only
* do not need to have any UI - all other plugins are visible somewhere
* Local user profile view hook (not part of  MDL-16438)
* may apply backup/restore xml transformations (not part of  MDL-16438)
* ''My Moodle'' hooks (not part of  MDL-16438)
 
 
List of normal plugin features:
* db/version.php - version of script
* db/install.xml - executed during install (new version.php found)
* db/install.php - executed right after install.xml
* db/upgrade.php - executed after version.php change
* db/access.php - capabilities
* db/events.php - event handlers
* db/messages.php - messaging info
* db/external.php - web services api, not finished yet
* localization string files
* plugins of the same type are installed/upgraded in alphabetical order


[[Category:Developer|Local customisation]]
[[Category:Developer|Local customisation]]

Latest revision as of 20:51, 7 April 2011

Local customisations
Project state Implemented
Tracker issue MDL-17376, MDL-16438
Discussion http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
Assignee Petr Škoda (škoďák), some parts were originally proposed and implemented in 1.9 by Penny Leach

Moodle 2.0


The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

Custom /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
  • extending the navigation block with custom menus [1]

Standard plugin features:

  • /local/xxx/version.php - version of script (must be incremented after changes)
  • /local/xxx/db/install.xml - executed during install (new version.php found)
  • /local/xxx/db/install.php - executed right after install.xml
  • /local/xxx/db/uninstall.php - executed during uninstallation
  • /local/xxx/db/upgrade.php - executed after version.php change
  • /local/xxx/db/access.php - definition of capabilities
  • /local/xxx/db/events.php - event handlers and subscripts
  • /local/xxx/db/messages.php - messaging registration
  • /local/xxx/db/external.php - web services and external functions descriptions
  • /local/xxx/lang/en/local_pluginname.php - language file

The xxx is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.

List of differences from normal plugins:

  • always executed last during install/upgrade - guaranteed by order of plugins in get_plugin_types()
  • are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
  • can add admin settings to any settings page - loaded last when constructing admin tree
  • do not need to have any UI - other plugins are usually visible somewhere
  • some extra hooks (not implemented yet)

/local/xxx/db/messages.php

Example File Structure: <?php

/** 

* Defines message providers (types of messages being sent)
*
* @package mod-forum
* @copyright  1999 onwards  Martin Dougiamas  http://moodle.com
* @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

$messageproviders = array (

/// Ordinary single forum posts 

   'posts' => array (
   )

);

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. 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; // 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 "|".

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.

2.0 pre-upgrade script

You can use /local/upgrade_pre20.php script for any code that needs to 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.

This file is just included directly, there does not need to be any function inside. If the execution stops the script is executed again during the next upgrade. The first execution of lib/db/upgrade.php increments the version number and the pre upgrade script is not executed any more.

Customisations outside of /local/ directory

Forced settings

Sometimes it is useful to force some settings and prevent any changes of these settings via the standard admin UI. It is possible to hardcode these settings in config.php.

In case of course settings it is very simply, the values are assigned directly to $CFG properties. In case of plugins the values are specified in a multidimensional array in $CFG->force_plugin_settings.

Sample code in config.php $CFG->allowobjectembed = 0; $CFG->forced_plugin_settings = array('page'=>array('displayoptions'=>5, 'requiremodintro'=>1), 'folder'=>'requiremodintro'=>1);

Local language customisations

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": moodledata/lang/en_local <?php 

 $string['login'] = 'Sign in';

See also https://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

Direct code modifications

This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

Direct database modifications

Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

Local customisations in previous versions

Previous versions include only partial support for customisations in /local/ directory.

List of local customisations in 1.9.x:

  • /local/cron.php - custom cron jobs
  • /local/settings.php - custom admin settings
  • /local/db/upgrade.php - general modifications
  • /local/lang/* - custom strings
  • /local/lib.php - local_delete_course()

Migration from old 1.9.x /local/:

  • local/* needs to be copied to new directory
  • local/xxxx/db/install.php is intended for first installation, originally everything was in upgrade.php
  • events are used instead of hooks
  • upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

See also

Retrieved from "https://docs.moodle.org/19/en/index.php?title=Development:Local_customisation&oldid=82644"
Powered by MediaWiki