ilp block

This page contains some documentation of writing plugins for the Moodle 2 version of the ILP block. This is a work in progress and is currently being authored by a third-party developer, not a member of the team who developed the block and its plugin architecture, so please bear that in mind when reading this. The information here is based on a discussion and demonstration with the developers, plus some of my own research and assumptions.

Plugin Types

The ILP block provides a framework for recording reports regarding students, displaying them, and reporting on other student data. It also provides a set of plug-ins to this framework. The current plug-in types include:

• Form Elements - These are the different elements that can be added to reports
• Dashboard Elements - These are used to display content on the student dashboard
• Dashboard Tabs - These display the main content of the ILP
• MIS - These provide links to MIS data (?)
• Dashboard Templates - These control the appearance and layout of the student dashboard

Note that these are *not* Moodle plugins in the sense that you may be used to. The ILP's plugin architecture is completely seperate from that of Moodle.

Writing Plugins

A good place to start is by modifying an existing plugin of the same type as the one you want to create.

Form Elements

A form element consists of 2 files, which live in blocks/ilp/classes/form_elements/plugins:

ilp_element_plugin_{plugin_name}.php

• The file must include blocks/ilp/classes/form_elements/ilp_element_plugin.php, as this file defines ilp_element_plugin require_once($CFG->dirroot.'/blocks/ilp/classes/form_elements/ilp_element_plugin.php');
• This file defines a class called ilp_element_plugin_{plugin_name} as an extension of ilp_element_plugin.

class ilp_element_plugin_text_area extends ilp_element_plugin {

public $tablename; public $data_entry_tablename; public $minimumlength; //defined by the form creator to validate user input public $maximumlength; //defined by the form creator to validate user input

• The parent class will automatically provide an interface to the ILP's database via $this->dbc, and to the database manager via $this->dbman.
• The constuctor must set $this->tablename and $this->data_entry_tablename. These are 2 tables that will be created in the database to store the configuration for each instance of the plugin (when it is added to a report), and the data for each entry using the plugin (when someone fills in a report that uses the plugin), respectively. function __construct() {

   	$this->tablename = "block_ilp_plu_are";
   	$this->data_entry_tablename = "block_ilp_plu_are_ent";
   	
   	parent::__construct();
   }

• TODO: document the load() method
• The install() method allows you to add fields and keys to the tables defined by the constructor. There is no install.xml for ILP plugins, so you need to use the Data definition API to do this. You should find that you can still use the XMLDB editor to define your tables, then use the PHP code it genreates for upgrade scripts to write this method for you. Remember to replace any generated $dbman calls with $this->dbman.
• The uninstall() method lets you run code to drop tables or data as necessary to remove the plugin from the database.
• The audit_type() method should return a string that's used to identify the plugin type in logs etc. public function audit_type() {

   return get_string('ilp_element_plugin_text_area_type','block_ilp');

}

• The language_strings() method takes the place of the lang file (I'm not sure how/if this supports localisation). The $string array is passed the function as a reference, the strings are added to the array, and then $string is returned. The strings are then accessible as part of the block_ilp component, and their identifiers should be prefixed with the full plugin name function language_strings(&$string) {

       $string['ilp_element_plugin_text_area'] 		= 'Textarea';
       $string['ilp_element_plugin_text_area_type'] 	= 'Textarea';
       $string['ilp_element_plugin_text_area_description'] = 'A textarea';
       ...
       
       return $string;
   }

• delete_form_element() defines the code required to delete an instance of the field from a report public function delete_form_element($reportfield_id) {

   	return parent::delete_form_element($this->tablename, $reportfield_id);
   }

• entry_form() adds the fields to report form, using the Form Definition API. The $mform object is passed to the function, which then adds elements to the form as it would in the form class's own definition() method.
• entry_process_data() is passed the data submitted to the plugin's fields for any processing that needs to be done before it is inserted into the database. Simple elements can just use the parent method which will create or update a record in the plugin's data table. More complex elements can hand of the processing to entry_specific_process_data, which can do specialist processing. public function entry_process_data($reportfield_id,$entry_id,$data) {

   return $this->entry_specific_process_data($reportfield_id,$entry_id,$data); 	

}

public function entry_specific_process_data($reportfield_id, $entry_id, $data) {

   // do processing

}

ilp_element_plugin_{plugin_name}_mform.php

This file defines the form used to adding an instance of the field to a report. Think of it as the form for creating and editing entries in the $tablename table you defined in the ilp_element_plugin_{plugin_name}.php file.

• The file must start by including blocks/ilp/classes/form_elements/ilp_element_plugin_mform.php, which defines the ilp_element_plugin_mform class.require_once($CFG->dirroot.'/blocks/ilp/classes/form_elements/ilp_element_plugin_mform.php');
• The file defines a class called ilp_element_plugin_{plugin_name}_mform, which extends ilp_element_plugin_mform class ilp_element_plugin_text_area_mform extends ilp_element_plugin_mform {
• The class has 3 abstract methods which must be overridden:
  • specific_definition() allows you to add fields to the form. It will already have a fields to set the label, description, and whether the field is required. You can add any other fields using the Form Definition API. It recieves $mform as its only arugument
  • specific_validation() allows you define validation for the fields added by specific_definition(). It works just like the standard moodleform validation() method.
  • specific_process_data() recieves the $data object as its only arugment, and allows you to do any processing required for your fields.

Dashboard Tabs

A dashboard tab defines consits of a PHP class with an optional HTML template and some Javascript. The files live in blocks/ilp/classes/dashboard/tabs

ilp_dashboard_{pluginname}_tab

• This file starts by including ilp_dashboard_tab.php which defines the ilp_dashboard_tab class require_once($CFG->dirroot.'/blocks/ilp/classes/dashboard/ilp_dashboard_tab.php');
• Then a class is defined called ilp_dashboard_{pluginname}_tab, which extends ilp_dashboard_tab class ilp_dashboard_reports_tab extends ilp_dashboard_tab {
• The constructor recieves the student ID and course ID as arguments.
• The display_name() method returns the string to display on the tab itself function display_name() {

   return    get_string('ilp_dashboard_reports_tab_name','block_ilp');

}

• define_second_row() allows a second row of tabs to be defined. The row should be defined in $this->second_row as an array of arrays containing an id, link and name for each second row tab. Read the comments in an existing example.function define_second_row() {

...

   // the tabitem and selectedtab query string params are added to the linkurl in the
   // second_row() function
   $this->secondrow[]    =    array('id'=>$r->id,'link'=>$this->linkurl,'name'=>$r->name);

... }

• define_third_row() tab allows for a third row of tabs, if you really want
• display() returns the content of the tab as a string of HTML. If you want, you can use an HTML template defined in ilp_dashboard_{pluginname}_tab.html by setting up the variables it requires, including it and capturing the output with an output buffer, then returning it. Alternatively, you could use Moodle's [Output API] to generate the HTML to be returned. It recieves the $selectedtab as its only argument.
• language_strings() functions in the same way as for Form Elements, above.
• config_form() recieves an $mform as its only arugment, to which you can add fields to be displayed on the screen where the tab can be enabled or disabled.
• Additional methods can be defined here as required for use within the class.
• A Javascript module can be defined in ilp_dashboard_{pluginname}_tab.js and a $PAGE->requires_js_init_call added to the display() method to initialise it.

iLP database table relationships

iLP-DB-relationships.pdf