Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Subplugins: Difference between revisions

From MoodleDocs
(ja link)
 
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==Defining sub-plugin type==
==Defining sub-plugin type==


{{Moodle 2.5}}{{Moodle 2.6}}
{{Moodle 2.6}}


Sub-plugins are supported in following plugin types:
Sub-plugins are supported in following plugin types:
* activity modules
* activity modules
* html editors (since 2.5)  
* html editors (since 2.4)  
* local plugins (since 2.6)  
* local plugins (since 2.6)  
* admin tools (since 2.6)
* admin tools (since 2.6)
===db/subplugins.json===
{{Moodle 3.8}}
Starting with Moodle 3.8, the subplugins should be defined in the <tt>db/subplugins.json</tt> file. For example, from  <tt>mod/workshop/db/subplugins.json</tt>:
<syntaxhighlight lang="json">
{
    "plugintypes": {
        "workshopform": "mod/workshop/form",
        "workshopallocation": "mod/workshop/allocation",
        "workshopeval": "mod/workshop/eval"
    }
}
</syntaxhighlight>
If you have a plugin supporting multiple versions, then you should create the <tt>db/subplugins.json</tt> file, as well as a <tt>db/subplugins.php</tt> variant which contains the following:
<syntaxhighlight lang="php">
<?php
$subplugins = (array) json_decode(file_get_contents(__DIR__ . "/subplugins.json"))->plugintypes;
</syntaxhighlight>


===db/subplugins.php===
===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>:
Each activity module can define a set of sub-plugin '''types''' (not to be confused with the subplugins themselves) 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>
<syntaxhighlight lang="php">
$subplugins = array(
$subplugins = array(
     'workshopform'      => 'mod/workshop/form',
     'workshopform'      => 'mod/workshop/form',
Line 18: Line 40:
     'workshopeval'      => 'mod/workshop/eval',
     'workshopeval'      => 'mod/workshop/eval',
);
);
</code>
</syntaxhighlight>


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.
Line 25: Line 47:


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:
<code php>
<syntaxhighlight lang="php">
$string['subplugintype_workshopallocation'] = 'Submissions allocation method';
$string['subplugintype_workshopallocation'] = 'Submissions allocation method';
$string['subplugintype_workshopallocation_plural'] = 'Submissions allocation methods';
$string['subplugintype_workshopallocation_plural'] = 'Submissions allocation methods';
Line 32: Line 54:
$string['subplugintype_workshopform'] = 'Grading strategy';
$string['subplugintype_workshopform'] = 'Grading strategy';
$string['subplugintype_workshopform_plural'] = 'Grading strategies';
$string['subplugintype_workshopform_plural'] = 'Grading strategies';
</code>
</syntaxhighlight>


===Naming rules and recommendations===
===Naming rules and recommendations===


#sub-plugin type names must use only letters [a-z]+
#sub-plugin type names must use only letters [a-z]+
# 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 types must be globally unique - they must not collide with any other plugin type, core subsystem or any other sub-plugin type
# sub-plugin type names must be short because there are limits on database table name lengths
# sub-plugin type names must be short because there are limits on database table name lengths


Line 47: Line 69:
In Moodle 2.5 the class was named <tt>plugininfo_plugintype</tt> and was expected to be in <tt>plugindir/adminlib.php</tt> file.
In Moodle 2.5 the class was named <tt>plugininfo_plugintype</tt> and was expected to be in <tt>plugindir/adminlib.php</tt> file.


Since Moodle 2.6 the class has to be called <tt>\plugintype_pluginname\pluginfo\subtypename</tt> and is expected to be in <tt>plugindir/classes/pluiginfo/subtypename.php</tt> file.
Since Moodle 2.6 the class has to be called <tt>\plugintype_pluginname\plugininfo\subtypename</tt> and is expected to be in <tt>plugindir/classes/plugininfo/subtypename.php</tt> file.
 
Here is an example of the class for a plugin called mod_feed and subtype called feedview (doc comments omitted for brevity):
 
<syntaxhighlight lang="php">
namespace mod_feed\plugininfo;
class feedview extends \core\plugininfo\base {
}
</syntaxhighlight>


===Uninstallation support===
===Uninstallation support===
{{Moodle 2.6}}
{{Moodle 2.6}}


Since Moodle 2.6 sub-plugin types may define explicit uninstallation method. It is useful if you need to cleanup up some db tables or settings when uninstalling individual sub-plugins.
Since Moodle 2.6 sub-plugin types may define custom uninstallation method. It is useful if you need to cleanup up some db tables or settings when uninstalling individual sub-plugins.


===Management page===
===Management page===
Line 72: Line 102:
===Distribution of sub-plugins===
===Distribution of sub-plugins===


Basic se of sub-plugins is usually distributed with each add-on. It is also possible to submit add-on sub-plugins separately.
Basic set of sub-plugins is usually distributed with each add-on. It is also possible to submit add-on sub-plugins separately.


[[Category:Plugins]]
[[Category:Plugins]]
[[ja:サブプラグイン]]

Latest revision as of 15:07, 11 July 2023

Defining sub-plugin type

Moodle 2.6


Sub-plugins are supported in following plugin types:

  • activity modules
  • html editors (since 2.4)
  • local plugins (since 2.6)
  • admin tools (since 2.6)

db/subplugins.json

Moodle 3.8


Starting with Moodle 3.8, the subplugins should be defined in the db/subplugins.json file. For example, from mod/workshop/db/subplugins.json:

{
    "plugintypes": {
        "workshopform": "mod/workshop/form",
        "workshopallocation": "mod/workshop/allocation",
        "workshopeval": "mod/workshop/eval"
    }
}

If you have a plugin supporting multiple versions, then you should create the db/subplugins.json file, as well as a db/subplugins.php variant which contains the following:

<?php

$subplugins = (array) json_decode(file_get_contents(__DIR__ . "/subplugins.json"))->plugintypes;

db/subplugins.php

Each activity module can define a set of sub-plugin types (not to be confused with the subplugins themselves) 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 recommendations

  1. sub-plugin type names must use only letters [a-z]+
  2. sub-plugin types must be globally unique - they must not collide with any other plugin type, core subsystem or any other sub-plugin type
  3. sub-plugin type names must be short because there are limits on database table name lengths

plugininfo class

Moodle 2.6


Developers should always define a plugininfo class that describes the properties of subplugins.

In Moodle 2.5 the class was named plugininfo_plugintype and was expected to be in plugindir/adminlib.php file.

Since Moodle 2.6 the class has to be called \plugintype_pluginname\plugininfo\subtypename and is expected to be in plugindir/classes/plugininfo/subtypename.php file.

Here is an example of the class for a plugin called mod_feed and subtype called feedview (doc comments omitted for brevity):

namespace mod_feed\plugininfo;
class feedview extends \core\plugininfo\base {
}

Uninstallation support

Moodle 2.6


Since Moodle 2.6 sub-plugin types may define custom uninstallation method. It is useful if you need to cleanup up some db tables or settings when uninstalling individual sub-plugins.

Management page

Moodle includes only basic listing of installed sub-plugins and support for sub-plugin uninstallation.

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 lib/editor/tinymce/ for a real example.

Distribution of sub-plugins

Basic set of sub-plugins is usually distributed with each add-on. It is also possible to submit add-on sub-plugins separately.