Collections

Collection is a basic data structure in programming. In traditional PHP programming, array is used widely to represent collection data structure. A PHP array is a mix of cardinal-indexed array and hash table.

To enable object-oriented manipulation of collections, PRADO provides a set of powerful collection classes. Among them, the TList and TMap are the most fundamental and usually serve as the base classes for other collection classes. Since many PRADO components have properties that are of collection type, it is very important for developers to master the usage of PRADO collection classes.

Using `TList`

A TList object represents a cardinal-indexed array, i.e., an array (object) with the index 0, 1, 2, ...

TList may be used like a PHP array. For example,

$list=new TList; // create a list object ... $item=$list[$index]; // read the item at the specified index $list[]=$item; // append the item at the end $list[$index]=$item; // replace the item at the specified index unset($list[$index]); // remove the item at $index if(isset($list[$index])) // test if the list has an item at $index foreach($list as $index=>$item) // traverse each item in the list

To obtain the number of items in the list, use the Count property. Note, do not use count($list), as it always returns 1.

In addition, TList implements a few commonly used convenient methods for manipulating the data in a list. These include

clear(): removes all items in the list.
contains(): tests if the list contains the specified item.
indexOf(): obtains the zero-based index of the specified item in the list.
toArray(): returns an array representation of the items in the list.
copyFrom(): populates the list with data from an array or traversable object (including TList). Existing items will be removed first.
mergeWith(): appends the list with data from an array or traversable object (including TList).

Using `TList`-based component properties

As aforementioned, many PRADO component properties are based on TList or TList-derived collection classes. These properties all share the above usages.

For example, TControl (the base class for all PRADO controls) has a property called Controls which represents the collection of child controls. The type of Controls is TControlCollection which extends TList. Therefore, to append a new child control, we can use the following,

$control->Controls[]=$newControl;

To traverse through the child controls, we can use,

foreach($control->Controls as $childControl) ...

Another example is the Items property, available in list controls, TRepeater, TDataList and TDataGrid. In these controls, the ancestor class of Items is TList.

Extending `TList`

Often, we want to extend TList to perform additional operations for each addition or removal of an item. The only methods that the child class needs to override are insertAt() and removeAt(). For example, to ensure the list only contains items that are of TControl type, we can override insertAt() as follows,

public function insertAt($index,$item) { if($item instanceof TControl) parent::insertAt($index,$item) else throw new Exception('TControl required.'); }

Using `TMap`

A TMap object represents a hash table (or we say string-indexed array).

Similar to TList, TMap may be used like an array,

$map=new TMap; // create a map object ... $map[$key]=$value; // add a key-value pair unset($map[$key]); // remove the value with the specified key if(isset($map[$key])) // if the map contains the key foreach($map as $key=>$value) // traverse the items in the map

The Count property gives the number of items in the map while the Keys property returns a list of keys used in the map.

The following methods are provided by TMap for convenience,

clear(): removes all items in the map.
contains(): tests if the map contains the specified key.
toArray(): returns an array representation of the items in the map.
copyFrom(): populates the map with data from an array or traversable object (including TMap). Existing items will be removed first.
mergeWith(): appends the map with data from an array or traversable object (including TMap).

Using of `TAttributeCollection`

TAttributeCollection is a special class extending from TMap. It is mainly used by the Attributes property of TControl.

Besides the normal functionalities provided by TMap, TAttributeCollection allows you to get and set collection items like getting and setting properties. For example,

$collection->Label='value'; // equivalent to: $collection['Label']='value'; echo $collection->Label; // equivalent to: echo $collection['Label'];

Note, in the above $collection does NOT have a Label property.

Unlike TMap, keys in TAttributeCollection are case-insensitive. Therefore, $collection->Label is equivalent to $collection->LABEL.

Because of the above new features, when dealing with the Attributes property of controls, we may take advantage of the subproperty concept and configure control attribute values in a template as follows,

<com:TButton Attributes.onclick="if(!confirm('Are you sure?')) return false;" .../>

which adds an attribute named onclick to the TButton control.

$Id$

Collections

Using TList

Using TList-based component properties

Extending TList

Using TMap

Using of TAttributeCollection

Using `TList`

Using `TList`-based component properties

Extending `TList`

Using `TMap`

Using of `TAttributeCollection`