Developer Area/Local customizations

Mahara includes a /local directory. This is a central place which provides hooks for several types of local customizations, that allow a Mahara site to change the behavior of Mahara without editing Mahara core code.

Why /local?

If you're new to website administration, you may be asking, why bother? If I want to make a customization to my Mahara site, why not just edit the Mahara code directly?

The answer is that editing Mahara core code makes updates difficult. The Mahara project regularly releases updates, some quite extensive. If you haven't customized your Mahara code at all, you can simply replace your existing code base with the updated one. But if you have customized a Mahara core file, and our updates change that file, you will either have to lose your updates or figure out how to apply them to the new version of the file. Using proper revision control, especially git, can make this process easier, but it's still easiest to avoid it by minimizing changes to the Mahara core code.

The "/local" directory is just one way to customize Mahara. Plugins and Themes are the other main ways to do this. See Customising for the full list of options.

What /local can do

Note that in the past, new hooks in /local have not always been well documented. So when in doubt, your best bet for the latest information will be to search the codebase.

Also note that many of the files you can place under /local are already present in Mahara core. So you do have to "edit core" in order to edit them. However, these files will always be designed in such a way that you can safely and easily overwrite them with your own files during the upgrade process.

Install hooks

The file local/install.php contains functions named localpreinst() and localpostinst(). These are called during the Mahara installation process; localpreinst() is called early during the installation process, and localpostinst() is called as the final step in the installation process.

These methods are defined empty. You may override them to add your own code to the preinstall and postinstall process.

DB hooks

The /local directory has its own "version.php", "install.xml", and "upgrade.php" files. These act similarly to how they would for a standard Mahara plugin. When Mahara is first being installed, any database structures defined in local/install.xml will be created, and the version number in local/version.php will be stored in the database (as the config value "localversion"). If the version in local/version.php is incremented, Mahara will detect this and prompt the admin to run the upgrade script, running any appropriate upgrade sections in local/upgrade.php.

Custom language strings

You can override language strings by placing lang files under /local/lang. This is particularly useful if you only need to change one or two language strings.

See Developer_Area/Language_strings#Custom_lang_strings_in_.2Flocal for details.

Override help Custom help files

You can override the content of help filesHelp files can be customized by placing help files under /local/lang.

See Developer_Area/Language_strings#Custom_help_files_in_.2Flocal for details.

Custom theme overrides

You can provide custom theme templates under /local/theme/templates, as if this were the "templates" directory of a theme. Likewise, you can customize static assets like images by placing them under /local/theme/static. See Customising/Themes/1.10#Local_theme_overrides

Prior to Mahara 1.10, template files placed in /local in this way were placed in order of precedence below the current theme, but above any parent themes. This made them mostly useful for supporting the creation of new pages, rather than overriding existing pages. Also prior to Mahara 1.10, the template files of plugins, even those that ship with Mahara, cannot be customized via the /local directory. As of Mahara 1.10 these restrictions have been lifted; /local theme contents come first in precedence, and /local can include theme contents for plugins.

Miscellaneous hook functions in /local/lib.php

The Mahara code base contains a number of places where the presence of a local "hook" function is checked for, and if present, this function is executed. These are meant to provide an easy method for site administrators to change core functionality of Mahara without changing core code.

As of Mahara 1.10, all of these are documented in the header to the /local/lib.php file. Here are some of the highlights:

• local_can_remove_viewtype($viewtype): Can be used to block users from being able to delete certain types of views
• local_get_allowed_blocktypes($category, $view): Can be used to remove some blocktypes from the page builder.
• local_get_allowed_blocktype_categories($view): Can be used to remove some blocktype categories from the page build.r
• local_header_top_content(): Returned data is printed at the top of the "head" tag on most pages. (If you only need to print static content, as of Mahara 1.9 you can do this using the $cfg->additionalhtmlhead config option, described in lib/config-defaults.php)
• local_main_nav_update(&$menu): Can be used to modify the contents of the main navigation menu
• local_right_nav_update(&$menu): Can be used to modify the contents of the sidebar
• local_register_submit(&$values): Pre-registration hook. Content added to $values['extra'] will be automatically stored in the database in usr_registration.extra
• local_post_register($registration): Post-registration hook. Meant to be a place where data stored in usr_registration.extra can be retrieved and applied to the now-registered user.
• local_init_user(): Hook function, called on each pageload immediately after the global $USER object is initiated.