tool pluginkenobi

Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

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 have two options, the option to use a recipe file for generating the plugin type (mandatory) and the target directory for the plugin files (optional):

 $php generate.ph --recipe=recipe.yaml --targetdir=~/demo/

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.

I have decided to use YAML for the recipe format. Included in the plugin is a standalone library for parsing the YAML format, 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 part of the user input that is required for all plugin types(validate and sanitize it) and invoke the corresponding generator classes with the appropiate options.

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 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	various
db_install_xml	various
db_install_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 10th - Choose a template and recipe format and a templating language.

The templating language chosen is Mustache because the templating engine is already part of Moodle and it is reasonable to expect that most of the Moodle developers are familiar with the language. For describing the recipe I am using YAML.

• June 16th - Create the CLI script for the plugin and the followind classes:
  • tool_pluginkenobi_recipe_processor, which will process the recipe into the format understood by the generator classes and the templating language. It also serves as a wrapper around the language used for describing the recipe (YAML).
  • tool_pluginkenobi_template_processor. It generates the contents of the plugin files by using the templating language (Mustache) on the template files. It too serves as a wrapper around the templating language.
  • tool_pluginkenobi_processor. It supervises the creation of the plugin files by invoking all the necessary generator classes.
  • tool_pluginkenobi_generator_base. This is the parent class for all generators. Each generator will extend this class and override methods as needed.

• June 23rd - Create generators for the following files or features:
  • language strings file. The class tool_pluginkenobi_lang_generator will generate all the files that go in the lang directory. These files are mandatory for all plugin types.
  • version.php file. The class name will be tool_pluginkenobi_version_generator. The file is mandatory for all plugin types.
  • settings (feature). The class name will be tool_pluginkenobi_settings_generator.
  • capabilities (feature). The class name will be tool_pluginkenobi_capabilities_generator and it will generate the db/access.php file.
  • install (feature). The class name will be tool_pluginkenobi_db_install_generator. It will generate two files: db/install.xml and db/install.php, which are need during plugin installation.
  • uninstall (feature). The class name will be tool_pluginkenobi_db_uninstall_generator. It will generate the db/uninstall.php file.
  • observers (feature). The class tool_pluginkenobi_observers_generator will generate the db/events.php file with the event observers as well as the observer classes and actions.
  • events (feature). Each event will be implemented as a class deriving \core\event\base and implemented in the classes/event/<event_name>.php directory in the plugin namespace.

These features have been chosen because they are used in many plugin types. All generators should have associated PHPUnit tests.

Generating a 'local' plugin type will also be implemented, which will use the above features.

• June 30th - Create generators for another plugin type. The plugin will be chosen based on its popularity in the Moodle plugins directory.

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

• August 7th - All generator classes should be implemented by now, as well as associated PHPUnit tests.

• August 12tht - 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.