Development Guide

Explorer, Tree Explorer

This introduction covers the new classes that should be introduced with ILIAS 4.4.

The explorer service Services/UIComponent/Explorer2 implements a user interface element for the presentation of hierarchical (tree) structures. It currently includes two main abstract classes ilExplorerBaseGUI and ilTreeExplorerGUI. The first one implements the general features, the second contains additional implementations for the use of tree objects of the Services/Tree service.

Step 1: Extending ilExplorerBaseGUI or ilTreeExplorerGUI

You first need to extend either ilExplorerBaseGUI or ilTreeExplorerGUI. If you are visualizing a struture that is based on a tree object from Services/Tree, extend ilTreeExplorerGUI, otherwise extend ilExplorerBaseGUI.

ilExplorerBaseGUI

This class

  • acts on nodes with a parent/child relationship
  • without any requirements how nodes are represented (e.g. they can be objects or associative arrays)
  • except that nodes can be identified by an ID (not necessarily an integer value).
The class provides the following features:
  • HTML generation of the UI element
  • Option to skip the root element in the presentation
  • Ajax Mode
  • Determination of link (href, onclick, target), icon (src, alt) and content of a node
  • Node Highlighting
The following abstract functions need to be implemented:
  • getRootNode(): This function should return the root node array or object.
  • getChildsOfNode($a_parent_node_id): This function should return all child nodes for a node ID.
  • getNodeContent($a_node): This function should return the content of a node.
  • getNodeId($a_node): This function should return the ID for a given node.
Additionally you may want to override these functions:
  • getNodeHref($a_node): Return the href attribute for the link of a node. (string)
  • getNodeTarget($a_node): Return the target attribute for the link of a node. This should be only used in rare cases, e.g. use  "_blank" to link to external pages. (string)
  • getNodeOnClick($a_node): Return the onclick attribute for the link of a node. Sometimes clicks on container nodes should just toggle (open/close) a node. This can be done by returning getNodeToggleOnClick($a_node) in getNodeOnClock($a_node). (string)
  • getNodeIcon($a_node): Return the icon path for a node. (string)
  • getNodeIconAlt($a_node): Return the alt attribute for the icon of a node. (string)
  • isNodeVisible($a_node): Determine whether a node is visible or not. (boolean)
  • isNodeHighlighted($a_node): Determine whether a node is highlighted or not. (boolean)
Furthermore the following methods allow to influence the representation:
  • setSkipRootNode($a_val): If true, the root node will not be included in the presentation.
  • setAjax($a_val): If true, childs will be retrieved by ajax calls. This should be activated, if you act on large structures.

Here an example using a static internal node array:

<?php
/* Copyright (c) 1998-2013 ILIAS open source, Extended GPL, see docs/LICENSE */
 
include_once("./Services/UIComponent/Explorer2/classes/class.ilExplorerBaseGUI.php");
 
/**
* Explorer example
*/

class ilMyExplorerGUI extends ilExplorerBaseGUI
{
private $nodes = array(
0 => array("id" => 0,
"content" => "Root Node",
"childs" => array(1, 2)),
1 => array("id" => 1,
"content" => "First Node",
"childs" => array()),
2 => array("id" => 2,
"content" => "Second Node",
"childs" => array(3)),
3 => array("id" => 3,
"content" => "Third Node",
"childs" => array())
);
 
//
// Abstract function that need to be overwritten in derived classes
//
 
/**
* Get root node.
*
* @return mixed root node object/array
*/

function getRootNode()
{
return $this->nodes[0];
}
 
/**
* Get childs of node
*
* @param string $a_parent_id parent node id
* @return array childs
*/

function getChildsOfNode($a_parent_node_id)
{
$childs = array();
foreach ($this->nodes[$a_parent_node_id]["childs"] as $c)
{
$childs[] = $this->nodes[$c];
}
return $childs;
}
 
/**
* Get content of a node
*
* @param mixed $a_node node array or object
* @return string content of the node
*/

function getNodeContent($a_node)
{
return $a_node["content"];
}
 
/**
* Get id of a node
*
* @param mixed $a_node node array or object
* @return string id of node
*/

function getNodeId($a_node)
{
return $a_node["id"];
}
 
}
 
?>

ilTreeExplorerGUI

This class extends the ilExplorerBaseGUI class and

  • requires an instance of ilTree (Services/Tree) in the constructor and
  • acts on associative arrays as delivered by ilTree.
It already provides standard implementations of:
  • getRootNode()
  • getChildsOfNode($a_parent_node_id)
  • getNodeId($a_node)
You only need to override
  • getNodeContent($a_node): Return the content a node. (string)
The following methods are additionally provided:
  • setOrderField($a_val): Key of the field that should be used for ordering child nodes.
  • setTypeWhiteList($a_val): Array of types (strings) that should be retrieved as nodes.
  • setTypeBlackList($a_val): Array of types (strings) that should not be retrieved as nodes.

Step 2: Calling your extended class

After you extended the class you build an instance and call your instance very similar to the use of ilTable2GUI instances. Important is the call of handleCommand() before getHTML(). The handleCommand() method handles internal commands of the explorer class, especially Ajax calls.

class ilParentGUI
{
...
 
/**
* Show Tree
*/

function showTree()
{
global $tpl;
 
include_once("./.../classes/class.ilMyExplorerGUI.php");
$exp = new ilMyExplorerGUI("my_expl_id", $this, "showTree");
if (!$exp->handleCommand())
{
$tpl->setLeftNavContent($exp->getHTML());
}
}
}