Development Guide

Field-Type Plugins

This plugin slot is introduced in ILIAS release 5.2

A Field-Type plugin allows you to customize ILIAS DataCollections by extending the existing list of possible field-types. Existing types would e.g. be Text, Number or Datetime, just to name a few. If these are not sufficient, you are now able to introduce a new one by configuring its representation and behavior, or setting restrictions.

Plugin Slot

This plugin slot is part of the component "Modules/DataCollection"  and called "FieldTypeHook". Therefore plugins of this type have to be installed in the designated ILIAS folder: 

Customizing/global/plugins/Modules/DataCollection/FieldTypeHook

Directory Structure

A field-type plugin has the following minimum file/directory structure. If needed, template or sql directories and files may be used (see general plugin documentation). Another language file than ilias_en.lang may be present instead.

<PluginName> (Directory)
	classes (Directory)
		class.il<PluginName>Plugin.php
		class.il<PluginName>FieldModel.php
		class.il<PluginName>FieldRepresentation.php
		class.il<PluginName>RecordFieldModel.php
		class.il<PluginName>RecordRepresentation.php
	lang (Directory)
		ilias_en.lang
	plugin.php

Example

The following example guides you through the implementation of a simple field-type plugin, thereby explaining the basic plugin structure and necessary functions. It defines a new DataCollection field, which acts like a text field but representing its text as strong.
This plugin is called "HelloWorld", so its location will be at:

Customizing/global/plugins/Modules/DataCollection/FieldTypeHook/HelloWorld

plugin.php

All plugins must include a plugin.php file.

<?php
 
// alphanumerical ID of the plugin; never change this
$id = 'hellow';
 
// code version; must be changed for all code changes
$version = '1.0.0';
 
// ilias min and max version; must always reflect the versions that should
// run with the plugin
$ilias_min_version = '4.4.000';
$ilias_max_version = '5.2.999';
 
// optional, but useful: Add one or more responsible persons and a contact email
$responsible = 'Michael Herren';
$responsible_mail = 'mh@studer-raimann.ch';
 
?>

classes/class.il<PluginName>Plugin.php

<?php
 
require_once('./Modules/DataCollection/classes/Fields/Plugin/class.ilDclFieldTypePlugin.php');
 
/**
 * Class ilHelloWorldPlugin
 *
 * @author  Michael Herren <mh@studer-raimann.ch>
 * @version 1.0.0
 */
class ilHelloWorldPlugin extends ilDclFieldTypePlugin {
 
	/**
	 * Get Plugin Name. Must be same as in class name il<Name>Plugin
	 * and must correspond to plugins subdirectory name.
	 *
	 * Must be overwritten in plugin class of plugin
	 *
	 * @return    string    Plugin Name
	 */
	function getPluginName() {
		return "HelloWorld";
	}
}

 The plugin class must inherit from ilDclFieldTypePlugin. It suffices to overwrite the method to receive the plugins name here.

classes/class.il<PluginName>FieldModel.php

<?php
require_once("./Modules/DataCollection/classes/Fields/Plugin/class.ilDclPluginFieldModel.php");
require_once("./Modules/DataCollection/classes/Helpers/class.ilDclRecordQueryObject.php");
 
/**
 * Class ilHelloWorldFieldModel
 *
 * @author  Michael Herren <mh@studer-raimann.ch>
 * @version 1.0.0
 */
class ilHelloWorldFieldModel extends ilDclPluginFieldModel {
	/**
	 * @param int $a_id
	 */
	public function __construct($a_id = 0) {
		parent::__construct($a_id);
 
		// if you want to use the dcl-storage locations you need to override the plugins default one (which is no location)
		$this->setStorageLocationOverride(1);
	}
 
	/**
	 * Returns a query-object for building the record-loader-sql-query
	 *
	 * @param string $filter_value
	 *
	 * @return null|ilDclRecordQueryObject
	 */
	public function getRecordQueryFilterObject($filter_value = "", ilDclBaseFieldModel $sort_field = null) {
		global $ilDB;
 
		$join_str = "INNER JOIN il_dcl_record_field AS filter_record_field_{$this->getId()} ON (filter_record_field_{$this->getId()}.record_id = record.id AND filter_record_field_{$this->getId()}.field_id = " . $ilDB->quote($this->getId(), 'integer') . ") ";
		$join_str .= "INNER JOIN il_dcl_stloc{$this->getStorageLocation()}_value AS filter_stloc_{$this->getId()} ON (filter_stloc_{$this->getId()}.record_field_id = filter_record_field_{$this->getId()}.id AND filter_stloc_{$this->getId()}.value LIKE " . $ilDB->quote("%$filter_value%", 'text') . ") ";
 
		$sql_obj = new ilDclRecordQueryObject();
		$sql_obj->setJoinStatement($join_str);
 
		return $sql_obj;
	}
}

This class describes the structure and model of the new field. Here we override getRecordQueryFilterObject to tell a DataCollection how to get the fields data. 

To do so, we build the correct SQL-Query string to fetch the data and add it to a new ilDclRecordQueryObject. Note that we name the tables inside the query (.. AS ..) with names containing the fields id. This helps to avoid having doubled table names when it's concatenated with the rest of the query.

Further we call setStorageLocationOverride(1), to tell the field model that we will use the storage location for this field.

classes/class.il<PluginName>FieldRepresentation.php

<?php
require_once('./Modules/DataCollection/classes/Fields/Plugin/class.ilDclPluginFieldRepresentation.php');
 
/**
 * Class ilHelloWorldFieldRepresentation
 *
 * @author  Michael Herren <mh@studer-raimann.ch>
 * @version 1.0.0
 */
class ilHelloWorldFieldRepresentation extends ilDclPluginFieldRepresentation {
 
	/**
	 * @param ilPropertyFormGUI $form
	 * @param int               $record_id
	 *
	 * @return ilDclTextInputGUI
	 */
	public function getInputField(ilPropertyFormGUI $form, $record_id = 0) {
		$input = new ilDclTextInputGUI($this->getField()->getTitle(), 'field_' . $this->getField()->getId());
		$this->setupInputField($input, $this->getField());
 
		return $input;
	}
 
 
	/**
	 * Add filter input to TableGUI
	 *
	 * @param ilTable2GUI $table
	 *
	 * @return null
	 */
	public function addFilterInputFieldToTable(ilTable2GUI $table) {
		$input = $table->addFilterItemByMetaType("filter_" . $this->getField()->getId(), ilTable2GUI::FILTER_TEXT, false, $this->getField()->getId());
		$this->setupFilterInputField($input);
 
		// return the current filter value
		return $this->getFilterInputFieldValue($input);
	}
 
}

This class is responsible for the fields representation, meaning its input field when editing or creating a record, and its filter item inside a table. Therefore we override getInputField and addFilterInputFieldToTable.

classes/class.il<PluginName>RecordFieldModel.php

<?php
require_once('./Modules/DataCollection/classes/Fields/Plugin/class.ilDclPluginRecordFieldModel.php');
/**
 * Class ilHelloWorldRecordFieldModel
 *
 * @author  Michael Herren <mh@studer-raimann.ch>
 * @version 1.0.0
 */
class ilHelloWorldRecordFieldModel extends ilDclPluginRecordFieldModel
{
	// here you could override record-value logic (e.g. Excel-Export formating, other storage-location mechanisms)
}

This class is responsible for handling the fields record-value logic. We don't need any special mechanism and therefore won't override anything for this example. 

classes/class.il<PluginName>RecordRepresentation.php

<?php
require_once('./Modules/DataCollection/classes/Fields/Base/class.ilDclBaseRecordRepresentation.php');
/**
 * Class ilHelloWorldRecordRepresentation
 *
 * @author  Michael Herren <mh@studer-raimann.ch>
 * @version 1.0.0
 */
class ilHelloWorldRecordRepresentation extends ilDclBaseRecordRepresentation {
 
	/**
	 * Outputs html of a certain field
	 * @param mixed $value
	 * @param bool|true $link
	 *
	 * @return string
	 */
	public function getHTML($link = true) {
		return "<strong>".$this->record_field->getValue()."</strong>";
	}
 
}

Define here how the fields record-value will be represented. If you don't override getHTML, the plain value will be returned. We add the html tags to represent the text as strong.

Hello World Plugin for ILIAS 5.2.x