tool pluginkenobi

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 scaffolding 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 scaffolding 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:

1. 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.
2. 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.
3. Identify shared characteristics between plugin types.
4. Create the class hierarchy for the code generators.
5. Examine existing plugins for implementation details of their functionality.
6. Choose a template format and a templating language. I am currently considering twig and mustache.
7. Create templates for the files used by most plugins and configuration for the most popular plugin types.
8. 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.
9. 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.
10. Create the web interface.
11. 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 scaffolding 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.
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)
mod	newmodule1, newmodule2
enrol	enrol
plagiarism	plagiarism
qtype	qtype
scormreport	scormreport

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 most 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	33

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.