Difference between revisions of "Subplugins"

Jump to: navigation, search
(Writing a sub-plugin)
Line 1: Line 1:
Sub plugins allow activity modules to be extended without having to change the module's code.
+
==Defining sub-plugin type==
  
Each activity module can define a set of subplugin types in <tt>db/subplugins.php</tt>.  The file must contain an array called <tt>$subplugins</tt>, with the plugin type as the key for the directory containing the plugins. For example, from <tt>mod/workshop/db/subplugins.php</tt>:
+
New plugins types may be define in activity modules and since 2.6 also in local plugins and admin tools - these are called sub-plugin types and sub-plugins.
 +
 
 +
===db/subplugins.php===
 +
 
 +
Each activity module can define a set of sub-plugin types in <tt>db/subplugins.php</tt>.  The file must contain an array called <tt>$subplugins</tt>, with the plugin type as the key for the directory containing the plugins. For example, from <tt>mod/workshop/db/subplugins.php</tt>:
 
<code php>
 
<code php>
 
$subplugins = array(
 
$subplugins = array(
Line 9: Line 13:
 
);
 
);
 
</code>
 
</code>
 +
 
This defines 3 plugin types, <tt>workshopform</tt>, <tt>workshopallocation</tt>, and <tt>workshopeval</tt>. The plugins themselves can be found in <tt>mod/workshop/form</tt>, <tt>mod/workshop/allocation</tt> and <tt>mod/workshop/eval</tt>, respectively.  Each of these directories can contain a number of plugins, each within it's own subdirectory.
 
This defines 3 plugin types, <tt>workshopform</tt>, <tt>workshopallocation</tt>, and <tt>workshopeval</tt>. The plugins themselves can be found in <tt>mod/workshop/form</tt>, <tt>mod/workshop/allocation</tt> and <tt>mod/workshop/eval</tt>, respectively.  Each of these directories can contain a number of plugins, each within it's own subdirectory.
 +
 +
===Language strings===
  
 
You also need to add an entry in the module's language strings to identify the subplugin(s). Again, using an example from Workshop in <tt>mod/workshop/lang/en/workshop.php</tt> one can find:
 
You also need to add an entry in the module's language strings to identify the subplugin(s). Again, using an example from Workshop in <tt>mod/workshop/lang/en/workshop.php</tt> one can find:
Line 21: Line 28:
 
</code>
 
</code>
  
 +
Naming rules and recommendation:
 +
* sub-plugin types must be globally unique - they must not collide with any other plugin type, core subsystem or any other subplugin-type
 +
* sub-plugin type names must be short because there are limits on database table name lengths
 +
 +
===Uninstallation support===
 +
{{Moodle 2.6}}
 +
TODO
 +
 +
===Management page===
 +
TODO
  
=== Writing a sub-plugin ===
+
== Writing a sub-plugin ==
  
 
A lot of the basic structure of a sub-plugin is the same as any other plugin. It can have a <tt>version.php</tt> (don't forget the object is '''$plugin''' not '''$mod'''), a <tt>lang</tt> directory, and can have a <tt>db</tt> directory with <tt>install.xml</tt> and all the others files can can go in there.
 
A lot of the basic structure of a sub-plugin is the same as any other plugin. It can have a <tt>version.php</tt> (don't forget the object is '''$plugin''' not '''$mod'''), a <tt>lang</tt> directory, and can have a <tt>db</tt> directory with <tt>install.xml</tt> and all the others files can can go in there.
Line 33: Line 50:
  
 
A subplugin can include a settings.php page but it will '''not''' be included automatically. It is the responsibility of the parent module's settings.php file to include the subplugin's settings pages. See mod/quiz/settings.php for a real example.  
 
A subplugin can include a settings.php page but it will '''not''' be included automatically. It is the responsibility of the parent module's settings.php file to include the subplugin's settings pages. See mod/quiz/settings.php for a real example.  
 +
 +
===Distribution of sub-plugins===
 +
 +
TODO
  
 
[[Category:Plugins]]
 
[[Category:Plugins]]

Revision as of 10:32, 22 October 2013

Defining sub-plugin type

New plugins types may be define in activity modules and since 2.6 also in local plugins and admin tools - these are called sub-plugin types and sub-plugins.

db/subplugins.php

Each activity module can define a set of sub-plugin types in db/subplugins.php. The file must contain an array called $subplugins, with the plugin type as the key for the directory containing the plugins. For example, from mod/workshop/db/subplugins.php:

$subplugins = array(
    'workshopform'       => 'mod/workshop/form',
    'workshopallocation' => 'mod/workshop/allocation',
    'workshopeval'       => 'mod/workshop/eval',
);

This defines 3 plugin types, workshopform, workshopallocation, and workshopeval. The plugins themselves can be found in mod/workshop/form, mod/workshop/allocation and mod/workshop/eval, respectively. Each of these directories can contain a number of plugins, each within it's own subdirectory.

Language strings

You also need to add an entry in the module's language strings to identify the subplugin(s). Again, using an example from Workshop in mod/workshop/lang/en/workshop.php one can find:

$string['subplugintype_workshopallocation'] = 'Submissions allocation method';
$string['subplugintype_workshopallocation_plural'] = 'Submissions allocation methods';
$string['subplugintype_workshopeval'] = 'Grading evaluation method';
$string['subplugintype_workshopeval_plural'] = 'Grading evaluation methods';
$string['subplugintype_workshopform'] = 'Grading strategy';
$string['subplugintype_workshopform_plural'] = 'Grading strategies';

Naming rules and recommendation:

  • sub-plugin types must be globally unique - they must not collide with any other plugin type, core subsystem or any other subplugin-type
  • sub-plugin type names must be short because there are limits on database table name lengths

Uninstallation support

Moodle 2.6

TODO

Management page

TODO

Writing a sub-plugin

A lot of the basic structure of a sub-plugin is the same as any other plugin. It can have a version.php (don't forget the object is $plugin not $mod), a lang directory, and can have a db directory with install.xml and all the others files can can go in there.

As a minimum, you will need the version.php file and a language file with 'pluginname' defined.

However the details of what APIs the sub-plugin has to provide depends on the type of sub-plugin it is. For example, and quiz report has to follow the rules for quiz reports that the quiz module sets, and a workshop allocation has to follow the rules set by the workshop module. When you create a new type of sub-plugin, you should document the expected API.

Settings pages

A subplugin can include a settings.php page but it will not be included automatically. It is the responsibility of the parent module's settings.php file to include the subplugin's settings pages. See mod/quiz/settings.php for a real example.

Distribution of sub-plugins

TODO