Difference between revisions of "ilp block"

Jump to: navigation, search
(Added documentation for ilp_element_plugin_{plugin_name}_mform.php)
(Fixed validation link)
Line 60: Line 60:
 
* The class has 3 abstract methods which must be overridden:
 
* 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 [[lib/formslib.php_Form_Definition|Form Definition API]]. It recieves $mform as its only arugument
 
** 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 [[lib/formslib.php_Form_Definition|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 [[https://docs.moodle.org/dev/lib/formslib.php_Validation|validation]]() method.
+
** specific_validation() allows you define validation for the fields added by specific_definition(). It works just like the standard moodleform [[lib/formslib.php_Validation|validation]]() method.
 
** specific_process_data() recieves the $data object as its only arugment, and allows you to do any processing required for your fields.
 
** specific_process_data() recieves the $data object as its only arugment, and allows you to do any processing required for your fields.

Revision as of 14:08, 17 May 2012

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.
    function language_strings(&$string) {
       $string['ilp_element_plugin_text_area'] 		= '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_specific_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 pass on the data to entry_process_data() which will create or update a record in the plugin's data table.
    public	function entry_specific_process_data($reportfield_id,$entry_id,$data) {
return $this->entry_process_data($reportfield_id,$entry_id,$data); }

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.