From 71a9120b8fc9f8771b603d195128a623b02a6554 Mon Sep 17 00:00:00 2001 From: xue <> Date: Thu, 18 May 2006 19:55:51 +0000 Subject: Added tutorial page for collections. --- .../protected/pages/Advanced/Collections.page | 135 +++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 demos/quickstart/protected/pages/Advanced/Collections.page (limited to 'demos/quickstart/protected/pages') diff --git a/demos/quickstart/protected/pages/Advanced/Collections.page b/demos/quickstart/protected/pages/Advanced/Collections.page new file mode 100644 index 00000000..181dc556 --- /dev/null +++ b/demos/quickstart/protected/pages/Advanced/Collections.page @@ -0,0 +1,135 @@ + + +

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-indxed 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 +

+ + +

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, +

+ + +

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. +

+ \ No newline at end of file -- cgit v1.2.3