View source for Local customisation (Moodle 1.9)

== Disclaimer ==

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

== General customisations ==

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.

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.

== local/ folder for 'hacky' customisations ==

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.

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.

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.

=== 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:

<code php>
$result = install_from_xmldb_file(dirname(__FILE__).'/install.xml');
</code>

==== local/db/upgrade.php ====

local/db/upgrade.php must look like:

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

    $result = true;

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

=== Local post-installation data insertion ===

In discussion - see http://tracker.moodle.org/browse/MDL-17440

=== Local capabilities ===

Just like core and modules, Moodle supports the use of a '''db/access.php''' inside local/ to define local capabilities.

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:

<code php>
$local_capabilities = array(
    'moodle/local:capability' => array(
        'captype'      => 'write',
        'contextlevel' => CONTEXT_SYSTEM,
        'riskbitmask'  => RISK_SPAM,
    ),
</code>

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:
<code php>
$string['local:capability'] =  'The language-string';
</code>

=== Local event subscriptions ===

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 [[Development:Events|Event API]] provides a very handy mechanism to do signal handling.

Local event handlers in <code>local/db/events.php</code> 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 / dropped''')

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.

This has not been included in Moodle 1.9 and the current (2011.01.17) status for http://tracker.moodle.org/browse/MDL-17446 is "won't fix".

=== Local stickyblocks targets ===

('''pending commit''')

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 is easily achieved by:

* 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() {
    return array(
        'custom_pagetype' => array(
            'id' => 'custom_pagetype',
            'lib' => '/local/lib.php',
            'name' => get_string('custom_pagetype', 'local')
        )
    );
}

</code>

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:

<code php>

class custom_pagetype extends page_base {

    // 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>

and map it with page_map_class:

<code php>
page_map_class('custom_pagetype', 'custom_pagetype');
</code>

=== Local user profile view hook ===

('''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.

* Create local/lib.php
* Create a function in there, local_user_view.

<code php>

function local_user_view($user, $course) {

    // capability check

    // extra stuff

}

</code>

=== 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
 $strings['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

=Local plugins in 2.0 proposal=
See [[Development:Local customisation]] - '''Author:''' [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]



[[Category:Developer|Local customisation]]