Advanced Data Types (ADT)

The ADT service has been introduced in 4.5 as part of the refactoring of the Advanced Metadata (AMD). For now it is experimental regarding its use as a general ILIAS Service. If you use the service you must be prepared for changes or even the possibility that the service may not become a future core feature and be abandoned.
 
This page is work in progress.

Basic concept

The advanced data types are designed as a wrapper for the PHP data types and are easily extendable. While their core usage is clearly in the data layer they are able to adapt to any layer or context with the bridge concept. Each ADT consists of 2 parts: the definition and the "value".

ilDateTime can be seen as "original" ADT. Add ilDatePresentation and ilDateTimeInputGUI and you have 90% of an ADT in the sense of this concept. ADTs are more generic and the definition has been split from the "value".

A word of warning: as the ADT service is way more object-oriented than the PHP data types, be aware of object references and their consequences.

ADT definition

The definition handles all properties of an ADT which are not value-specific. Most types can be configured, e.g. an integer ADT can have a minimum and/or maximum value. Other types are not configurable, e.g. boolean.
Once a ADT instance is built with a specific definition this definition cannot be changed anymore. Other classes may request a copy of the ADT's definition but that's about it. An ADT can validate its current "value" against its definition at anytime and thus have a clear state of valid or invalid.

ADT "value"

It is very important to grasp "value" as a very weakly defined concept regarding ADTs. While a value of an integer ADT matches the expectation by being a simple number (or null!) but what is the "value" of a location ADT? A location internally consists of 2 floats (latitude, longitude) and 1 integer (zoom) and so has a "complex value". It is really the whole point of ADTs to be able to have complex values and consistently handle those, which is not the case for PHP core data types.

Which this being said it becomes apparent that the comparison of 2 "values" is also complex. As already solved in the ilDateTime implementation all ADTs can be compared with internal methods: equals(), isLarger(), isSmaller() and so.

All ADTs can have null as a "value" (which is the case after constructing an instance) but its up to the definition if "null" is deemed valid or not.

So all ADTs have a "value" but that's about all one can say in a generic way. A good way to think about this problem is a PHP object instance $obj: what is its "value" and what happens when you "echo $obj;"?

Types

The existing core ADT types currently are:

• Boolean
• Date
• DateTime
• Enum
• Float
• Group
• Integer
• Location
• MultiEnum: 1-n
• MultiText: 1-n Text

Bridges

A bridge is the connector between ADTs and different contexts. Most of the time a context will supply a clearly defined container to add the ADT to. Each bridge type can have its own specific configuration. Current bridge types are:
 

• Form
• Search
• DB
• ActiveRecord
• Presentation

Form

Adds an ADT as input element to a ilPropertyFormGUI. What types of and how many input elements the ADT supplies is not known to the context. POST data handling and validation is part of the bridge responsibilities.

Search

Is similiar to form bridges as it is form-based but adds filter handling and comes in different sub-types: single, range and multi. As an example a date input can be

• single: simple date input field
• range: 2 fields (from - to)

DB

This bridge is about presentation of the "value" in a RDBMS. An ADT adds its "value" and the correct data types to an insert/update query and "converts" the DB presentation back into its internal one (once again think about dates/ilDateTime as a reference).
DB table properties as name, primary key and so on are NOT responsibilities of a single ADT, they have to be provided by the "caller" (see ilADTGroup).

ActiveRecord

This is currently only available for ilADTGroup and under discussion (see Active Records in this Dev Guide).

Presentation

This should be used for presentation in a HTML (template) context. There are currently 3 types:

• HTML: detailed presentation
• List: "shortened" presentation
• Sortable: get the current "value" in a sortable format

As there is no clearly defined "container" for this bridge this is most likely to change.

ilADTGroup

The group ADT consists of 1-n ADT elements. This is the probable basic building block for most applications and can be thought of as an alternative to ilObject. As it supplies the same bridges as the other ADT types it is very easy to define a number of ADT elements and handle them transparently in forms or other GUI widgets.

Example

$factory = ilADTFactory::getInstance();
$group_def = $factory->getDefinitionInstanceByType("Group");
$fname_def = $factory->getDefinitionInstanceByType("Text");
$group_def->addElement("first_name", $fname_def);
 
$group =$factory->getInstanceByDefinition($group_def);
$group_form = $factory->getFormBridgeForInstance($group);
 
$form = new ilPropertyFormGUI();
$group_form->setForm($form); // Kontext
$group_form->setTitle("Gruppe"); // ilFormSectionHeaderGUI
$group_form->addToForm();
 
$group_form-> importFromPost();
$form->checkInput(); // $_POST-Manipulation
If($group_form->validate())
{
     $first_name = $group_form->getADT()->getElement("first_name")->getText();
}