Development Guide

General: Implementing Plugins

Plugins extend or modify the functionality of ILIAS. The way they can do this is defined by a plugin slot provided by an ILIAS component. An example is the plugin slot for new question types of the test and assessment module.

You can get an overview of all defined plugin slots in the ILIAS administration under section "Modules, Services and Plugins". This will also list, the location of the plugins within the Customizing directory of ILIAS and their substructure.

A plugin contains:

  • A plugin.php file, defining version and ID of the plugin and the ILIAS version requirements.

  • An implementation of a plugin class, derived from the abstract plugin class of the plugin slot.

  • A set of language files, containing the text strings for the user interface. (optional)

  • A database update script, that creates and modifies the tables needed by the plugin.

  • A set of template files used to generate the user interface of the plugin. (optional)

plugin.php File

Every plugin must provide a plugins.php file in its main directory. The file must provide information about the id and version of the plugin, and the minimum and maximum ILIAS version requirements of the plugin.

<?php
 
// alphanumerical ID of the plugin; never change this
$id = "dhook";
 
// code version; must be changed for all code changes
$version = "0.0.2";
 
// ilias min and max version; must always reflect the versions that should
// run with the plugin
$ilias_min_version = "3.10.0";
$ilias_max_version = "3.10.999";
 
// optional, but useful: Add one or more responsible persons and a contact email
$responsible = "Jane Doe, John Doe";
$responsible_mail = "contact@doecompany.com";
?>

Plugin Class

The plugin class must be derived from the abstract plugin class of the plugin slot and be located in the classes directory of the plugin. The class name is derived from the plugin name, which is identical to the main directory name of the plugin: il<plugin_name>Plugin.

The plugin class should not implement too much application logic and must not contain any user interface related code. The plugin should use separate classes for these purposes. The plugin class is mainly used as adapter to basic services of ILIAS like language and template handling.

Language Files

The plugin may contain local language files for the definition of language strings used in the user interface components of the plugin. The language files must be located in the lang directory of the plugin and be named ilias_<lang_code>.lang. The format of the language files is different from the main language files of ILIAS. They just contain two columns separated by #:#. All variables are internally assigned to a language module identified by the IDs of the component, the slot and the plugin. These IDs are also internally prepended to the names of the language variables: <component_id>_<slot_id>_<plugin_id>.

// 
// English Language File for DummyHook Plugin
//
 
<!-- language file start -->
my_hook#:#My Hook
test_var#:#The Test Language Variable

To get the values of these variables, the plugin should use the txt() function of the plugin class object. The language module is loaded when the plugin object is instantiated. The txt() function automatically prepends the language variable prefix, so that the variables can be accessed easily.

// using language variables
$pl_obj = new ilDummyHookPlugin();
...
$text = $pl_obj->txt("test_var");

Database Update

If your plugin needs to store persistent data within the database, it needs to put table creation and alter statements into a database update file. The file contains a sequence of steps starting with a sequence ID tag, followed by a SQL statement and must be located at sql/dbupdate.php within the plugin directory.

All tables created and used by the plugin must start with a <component_id>_<slot_id>_<plugin_id> prefix.

<#1>
<?php
$fields = array(
	'id' => array(
		'type' => 'integer',
		'length' => 4,
		'notnull' => true
	),
	'name' => array(
		'type' => 'text',
		'length' => 10,
		'fixed' => false,
		'notnull' => false
	)
);
 
$ilDB->createTable("evnt_evhk_dhook_table1", $fields);
$ilDB->addPrimaryKey("evnt_evhk_dhook_table1", array("id"));
?>
 
<#2>
...

HTML Templates, CSS and Images

Template files must be located in the templates/ subdirectory within the plugin. To get template objects the plugin class provides a getTemplate() function. The addBlockFile() method of the plugin class can be used to replace a placeholder variable with a template file of the plugin.

// get the plugin
$pl = ilPlugin::getPluginObject(IL_COMP_SERVICE, "EventHandling", "evhk", "DummyHook");
 
// get template object
$tpl = $pl->getTemplate("tpl.my_template.html");
 
// replace placholder with template file
$pl->addBlockFile($tpl, "PLACEHOLDER", "my_block", "tpl.second_template.html");

Local CSS files are also stored in the templates subdirectory, e.g. templates/my.css. Images go to the templates/images subdirectory. To obtain these paths, use getStyleSheetLocation() and getImagePath().

// get an css path
$pl->getStyleSheetLocation("my.css");
 
// get an icon path
$pl->getImagePath("icon_tt.gif");

Including Class Files of Plugin

The application logic (or the user interface) that needs to be implemented for the plugin may require to spread the code on a number of class files. All these class files should be located in the classes/ directory of the plugin. If you need to include class files from the plugin within the plugin's code, never try to do this by using the full path of the plugin in the Customizing directory. Include these files "on demand" and use the method includeClass() of the plugin object for this purpose.

// get plugin object
$pl_obj = new ilDummyHookPlugin();
 
// include other class file of plugin
$pl_obj->includeClass("class.ilEvhkMyClass.php");

Using the Controller

If a plugin slot allows to plug in GUI classes, the slot has to provide a GUI class that will call the class(es) of the plugin using the $ilCtrl controller. The GUI class of the plugin has to declare these calls using the isCalledBy declaration tag.

/**
* Example: ilEventHookGUI is GUI class of slot, ilEvhkDummyHookGUI is GUI class of plugin
*
* @ilCtrl_IsCalledBy ilEvhkDummyHookGUI: ilEventHookGUI
*
* @author ...
* @version ...
*
*/
class ilEvhkDummyHookGUI
{
...
}

ILIAS will automatically parse these comments if a plugin is activated in the ILIAS administration. So in the case of plugins no special step is needed for this purpose in the database update script.

Configuration Screen in Administration (ILIAS 4.1.x and higher)

You can provide a configuration screen in the ILIAS administration if you implement the class class.il<plugin_name>ConfigGUI.php which should extend ilPluginConfigGUI.

<?php
 
include_once("./Services/Component/classes/class.ilPluginConfigGUI.php");
 
/**
 * Example configuration class
 *
 */
class ilDummyHookConfigGUI extends ilPluginConfigGUI
{
	/**
	* Handles all commmands, default is "configure"
	*/
	function performCommand($cmd)
	{
 
		switch ($cmd)
		{
			default:
				$this->$cmd();
				break;
 
		}
	}
 
	/**
	 * Configure
	 *
	 * @param
	 * @return
	 */
	function configure()
	{
		global $tpl, $ilToolbar, $ilCtrl;
 
		... Output configuration screen to $tpl...
	}
 
}
?>

The configuration screen is available under ILIAS administration -> Modules, Services and Plugins -> Plugins -> Administrat -> Configure

Example

The following file contains an example plugin for the EventHook plugin slot. Please note that this is still work in progress and major changes may be done until the final plugin architecture implementation for ILIAS 3.10.0.

DummyHook Plugin