tool pluginkenobi
tool pluginkenobi | |
---|---|
Type | Admin tools |
Set | N/A |
Downloads | N/A |
Issues | CONTRIB |
Discussion | dev.moodle.org forum |
Maintainer(s) | Alexandru Elisei |
Problem description
Moodle is the most widely used learning platform and is entirely open source, allowing everyone to freely modify and share their modifications. For this purpose Moodle has created the Moodle plugins directory where users can share their code with the entire community.
There is a wide variety of plugins that can be downloaded and installed from the plugins directory. To help maintaining a large number of plugins they have been split into different types. Each category imposes a set of rules on the plugin: the name and install location, the name of the classes and functions are all expected to follow a certain format; there are functionalities that should be implemented in a specific file that has the same role across plugin types. Regardless of type, each plugin is required to implement mandatory files (like version.php or a language string file). All files need to follow a specific format and adhere to the Moodle coding guidelines. Each plugin uses the Moodle core APIs in a specific way. Furthermore, there are code patterns and techniques that all plugins have in common. Moodle contributors need to be aware of all these conventions and for developing plugins they use the guides from the Moodle developer documentation and draw inspiration from existing plugins.
Project summary
The project’s aim is to make developing plugins a much easier task. Based on coding techniques used by existing plugins, on the guides and specifications found in the Moodle developer documentation, as well as on the user’s input, the tool will generate skeleton code that can will be used to build the plugin.
The developer will be able to specify the plugin type, name, features that will be implemented, details about the web interface and the CLI scripts and other plugin meta-data (like dependencies, author and copyright holder, version, stability level, and so on) the needed files will be generated, in the appropriate format and in accordance with the Moodle coding guidelines. The generator will use a set of template files unique for each plugin type and will support the ability to keep reference documentation for the each of the template files.
Project details and implementation
There are already code generators for moodle, like the moosh generate commands or the newmodule plugin, but their scope is limited to a very specific area of moodle. I plan to build on the above software and greatly expand their functionality to be able to generate code for the available plugin types.
The user will be able to interact with the plugin via a web interface located at Administration > Site administration > Plugins > Plugin generator and a command-line script located in the admin/tool/pluginkenobi/cli directory.
The web interface will consist of one main page where the user will be able to specify the plugin type and settings common to all plugins (like name, author, whether or not it will implement a web interface or a command-line script), followed by several web pages, each detailing one of the selected features or settings of the plugin. The second to last page will be a summary of all the options chosen by the user, asking him or her to confirm the settings, and on the final page the user will be presented with a set of links to the available documentation for the plugin type chosen, as well as general developer documentation (like the Moodle coding guidelines or the plugin contribution checklist).
Plugins can also be generated by using a recipe file. A recipe contains all the options needed for the generation of the specified plugin type. The recipe can be written by hand, or saved from the web interface after all the plugin options have been specified by the user.
Below is a mockup of the main web page for the plugin:
The command-line script will follow a syntax similar to the moosh generate commands, like for example:
generate activity-modules <list of options>
for generating skeleton code for an activity module plugin.
The templates used for generating the scaffold code will be located in a skel directory, each in a subdirectory with named after the plugin type they pertain to, except for templates used by more than one plugin (like the templates for generating a web form) which will be directly located in the skel directory.
These templates will be used by generator classes following the same directory hierarchy. A templating language will be used to manipulate the template files. Each plugin type will have its own configuration file specifying what generator classes it uses and the available options for each generator class.
Both the configuration file for each plugin type and the recipe files will be written using the same format. I am currently considering YAML. Included in the plugin will be a standalone library for parsing the YAML format like Spyc. I have chosen to include a standalone library so the user won't be forced to install additional software in order for the plugin to function correctly.
Coordinating the plugin creation will be a class called tool_pluginkenobi_processor (located at admin/tool/pluginkenobi/classes/processor.php) which will process the user input (validate and sanitize it), parse and validate the configuration file for the plugin type that the user wishes to create and invoke the corresponding generator classes with the appropiate options. The generator class will also be able process a receipe file or serialize all the plugin creation options and settings into a recipe file.
The creation of the plugin will involve the following steps:
- Create a list of all the features, settings and files that all plugins are expected to implement. This will be accomplished by reading the available Moodle documentation: plugin contribution, plugin contribution checklist and plugin files.
- Create a list of all the features, settings and files that each plugin type is expected to implement. This will be accomplished by reading the Moodle documentation of each plugin type from the plugin types web page.
- Identify shared characteristics between plugin types.
- Create the class hierarchy for the code generators.
- Examine existing plugins for implementation details of their functionality.
- Choose a template format and a templating language. I am currently considering twig and mustache.
- Create templates for the files used by most plugins and configuration for the most popular plugin types.
- Implement generator classes and PHPUnit tests for the above templates, as well as the CLI script which will use a recipe file. This should make testing the plugin a lot easier, as well as create a working prototype to be presented to the Moodle developer community.
- Create the templates and configuration files for the rest of the plugins. As the templates are created also implement the generator classes and PHPUnit tests.
- Create the web interface.
- Write documentation for the plugin in the Moodle docs.
Classes and template files
The template files used by the plugin are described below. They will reside in the skel directory. The file on the disk will have a suffix which depends on the templating language chosen (for example, if I choose twig the template version will correspond to the file version.twig). The generator class which will manipulate a template will have the same name as the template, prefixed with the Frankenstyle prefix for the plugin, and the suffix _generator (for example, for the template version the generator class will have the name tool_pluginkenobi_version_generator).
I will also use a class tool_pluginkenobi_generator which will serve as a wrapper for the templating language. This way the syntax of the templating language will be separated from the rest of the plugin.
Template | Used by | Notes |
---|---|---|
version | all | |
boilerplate | all | I have chosen to create a template for the boilerplate in case it gets modified, so I won't need to replace it in all the template files. |
lang | all | |
lib | various | |
locallib | various | |
settings | various | |
tests_phpunit | optional | Will be available as an option for all plugin types when generating the code. |
form | optional | |
tests_behat | optional | Will be available as an option for all plugin types if the user chooses to create a web form. |
backup | various | |
db_access_xml | various | |
db_access_php | various | |
db_upgrade | various | |
db_events | various | |
mod_form | mod | |
grade | mod | |
index | various | |
view | various | |
auth | auth | |
condition | availability | |
frontend | availability | |
yui_build | availability | |
yui_form_json | availability | |
yui_form_js | availability | |
yui_build | availability | |
block_simplehtml | block | |
edit_form | block, enrol | |
structure | calendartype | |
class_db | datafield | |
mod | datafield | |
unenrolself | enrol | |
renderer | format, qbehaviour, qtype, theme, gradingform | |
filter | filter | |
filterlocalsettings | filter | |
dump | gradeexport | |
export | gradeexport | |
grade_export | gradeexport | |
db_uninstall | local | |
db_messages | local | |
db_external | local | |
message_output | message | |
plagiarism_form | plagiarism | |
behaviour | qbehaviour | |
behaviourtye | qbehaviour | |
format | qformat | |
edit_qtype_form | qtype | |
questiontype | qtype | |
question | qtype | |
format | qformat | |
scorm_report | scormreport | |
engine | search | |
config | theme | |
define_class | profilefield | |
field_class | profilefield | |
server | webservice |
Existing templates
There are templates for several plugin types. They will be examine as part of the analysis of existing code generators for Moodle plugins. If any of the template files will get included in the plugin the authors will be given credit in a CREDITS.txt file.
In the table below are the templates that I've found during the preliminary research phase.
Plugin type | Template(s) | Inclusion in tool_pluginkenobi |
---|---|---|
mod | newmodule1, newmodule2 | The templates for the mandatory files (as described in the moodle docs) will be included (with the required modifications to make them compatible with tool_pluginkenobi template format). Other files present in the above templates will be implemented as 'features' (for example, the grade.php file). There will be separate generators for the files inside the db and backup folder, because those files will be generated for other plugin types. The db/mobile.php (added by Moodle 3.1) will also be generated from a template file. |
enrol | enrol | The templates are copies of the /enrol/self plugin. The templates will not be used, and more general templates will be created. The option to use a standard editing UI, introduced by Moodle version 3.1, will be added as a feature. |
plagiarism | plagiarism | The templates will be used, the docs reference the template as a starting point for a plagiarism plugin. The cron() function will be marked as deprecated (as per docs) and the new task api will be used instead. |
qtype | qtype | The template will be used, it is referenced in the docs. The various files residing in the db folder and the files needed for backup will be also be generated as part of features. |
scormreport | scormreport | The template will be used, it is mentioned in the docs as the base for a new scormreport plugin. The various files that reside inside the db folder will be generated as features. |
basic web form | part of moosh | The 'form' and 'form_client' templates will be used with midifications. I am considering adding the option to put on the form one of each form element as a starting point for the developer. |
gradereport | gradereport | The templates for this plugin type will be generated based on the information from the docs. |
gradeexport | gradeexport | It follows the instruction from the docs, the templates will be used. |
local | local | I will create my own template for the local plugin type. Most of the files that are part of a local plugin are used by other plugin types, there will be generator classes for each of these functions. |
message | message | The templates follow the specifications from the docs. |
profilefield | profilefield | The templates will be used, they follow the specification from the docs. |
Project schedule
- May 9th - Finish the preliminary plugin specifications and introduce the project to the Moodle community.
- May 21st - Create a draft of the class hierarchy used by the plugin.
- Read the available documentation about the various types of plugins.
- Install and experiment with the different plugins available in the Moodle plugins directory.
- May 22nd - Final version of the project specification page based on the input from the Moodle community.
- June 10th - Research and analysis of existing code generators for Moodle plugins.
- Get familiar with Moodle plugin types internals.
- Examine the code of existing plugins for implementation details.
- June 13th - Finalize the class hierarchy of the plugin.
- June 16th - Choose a template and configuration format and a templating language.
- June 19th - Materialize the findings from the previous phases into configuration files and templates for the most used files and the most popular plugin types.
These are the plugin types with the largest number of plugins in the Moodle plugin directory:
Plugin type | Entries |
---|---|
block | 283 |
mod | 168 |
theme | 126 |
local | 101 |
qtype | 55 |
auth | 35 |
atto | 33 |
enrol | 30 |
The plugin types for which the templates will be created in this phase will be chosen from the above table.
- June 21st - Create the cli script with support for generating skeleton code from a recipe file.
- June 27th - Create generator classes for the implemented templates. By now a working prototype of the tool should be available.
- July 1st - Create templates for the rest of the plugins.
- July 28th - All generator classes should be implemented by now, as well as associated PHPUnit tests.
- July 31st - Create a web interface for the plugin and associated behat tests.
- August 14th - Write the documentation for the plugin.
Note: The official GSoC coding period ends on August 23rd. I have reserved the last week of coding for various delays.