View source

Moodle has a mechanism that allows a number of places to be searched (in order) to find language strings or help files. This enables language strings and help to be packaged with optional plugins and avoids the step of having to copy the language files over to the language directory when a plugin is installed. This page provides some information about this mechanism which might be useful to plugin developers or those wishing to add a completely new pluggable feature to moodle.

This page covers both how to set up (core) Moodle to support a new plugabble resource and how to incorporate language elements in a plugin. Plugin writers really only need to read the last bit.

== Basic concepts ==

When it is required to lookup a string or point to a help file, two basic items of information are required. The first is the name of the string (or the help filename) and the name of the module in which it can be found. For example, '''get_string('editingquiz','quiz')''' returns "Editing Quiz" in the current language; a call to '''help.php?module=label&file=mods.html''' displays the help for a label, again in the current language. 

Plugin support extends this by defining a new format for the module name so that certain resources can both exist in core, the core distribution (and language packs) and be installed as options. The module name becomes ''type''_''plugin'', where ''type'' is a generic name common to the plugin type and ''plugin'' is the name of the individual item. To illustrate this, here is an example. Blocks are a pluggable resource - the ''type'' name is '''block_''' and the ''plugin'' name is the name of the individual block. Some examples of block module names are '''block_search''' (''type'' is '''block_''' and ''plugin'' is '''search''') and '''block_online_users''' (''type'' is '''block_''' and ''plugin'' is '''online_users''').

It is important to grasp that every block is now a discrete module type. This applies to all pluggable resources, so every, e.g., questiontype, authentication plugin, grade report is a separate module and will have its own language file and it's own directory for its help files. Not all plugin types define both language strings and help files but here is an example of what you might find for a pluggable resource that is included in core:

    Description: questiontype plugin for multichoice
    Module name: qtype_multichoice
    Language strings (English): lang/en_utf8/qtype_multichoice.php
    Help files directory (English): lang/help/qtype_multichoice/

All of the above must be in place for pluggable language and help strings to be a possibility for optional plugins.

NOTE: Module names cannot have numbers in them (only A-Z, a-z and underscore). This might be an issue to consider if you are moving from an existing architecture.

== Defining the search path(s) ==

The next step is to define the search locations for the plugin. This is only needed to define where the optional plugins will be installed, the standard help locations will be searched automatically. This is done by adding an entry to the array defined in the function '''places_to_search_for_lang_strings''' located in '''lib/moodlelib.php'''. This should be obvious from viewing the code but don't forget to include the underscore!

Viewing this function will also show you what Moodle elements currently support language string searching. This varies somewhat from version to version of Moodle as new locations are added.

== Adding language support to a plugin ==

If you are a plugin writer and you didn't read the first part of this you just need to be aware that your plugin name needs to start with the generic type for the plugin. For example all questiontype plugins '''must''' be prefixed '''qtype_''', all authentication plugins '''auth_'''. Moodle uses this prefix to identify the language search path. 

All that remains is now to add the language support to the optional plugin(s). This is done by creating a '''lang''' subdirectory in the plugin directory. The structure of the '''lang''' directory is then the same as the "main" language directory with one exception - the help directory name should '''not''' have the ''type_'' part of the module name (this might be a bug really!). Example...


    Description: Drag & Drop optional question type
    Module type: qtype_
    Module name: qtype_dragdrop
    Language file location (English): contrib/plugins/question/type/dragdrop/lang/en_utf8/qtype_dragdrop.php
    Help file directory (English): contrib/plugins/question/type/dragdrop/lang/en_utf8/help/dragdrop/

(Note: the help file directory is called '''dragdrop''' in the plugin. Compare this with the multichoice question type in core where the help folder is '''qtype_multichoice''')

== Advanced usage: what to do when your plugin type supports sub-plugins ==

{{Moodle 2.0}}

Suppose we are making a custom module, for example mod/mymod, and we would like to support a sub-plugin type, for example pluggable reports in mod/mymod/report. That is, we would like <code php>get_string('...', 'mymodreport_report1')</code> to look in mod/mymod/report/report1/lang/en_utf8/mymodreport_report1.php. Is there any way to do this without editing core code?

From Moodle 2.0 onwards, this is possible, you need to call the register_plugin_type method on the singleton string_manager class. That is
<code php>
string_manager::instance()->register_plugin_type('mymodreport', 'mod/mymod/report');
</code>
You must call that before any calls to get_string that need to access strings from a sub-plugin language file. Probably a good way to manage that is to put that line of code in mod/mymod/lib.php, and ensure that any code relating to your module includes that file.

== See also ==

* [http://phpdocs.moodle.org/HEAD/default/string_manager.html PHPdocs for the string_manager class]

[[Category:Developer]]
[[Category:Language]]