[Sommaire] [Imprimer]

   1  <com:TContent ID="body" >
   2  
   3  <h1 id="5501">Collections</h1>
   4  <p>
   5  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.
   6  </p>
   7  <p>
   8  To enable object-oriented manipulation of collections, PRADO provides a set of powerful collection classes. Among them, the <tt>TList</tt> and <tt>TMap</tt> 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.
   9  </p>
  10  
  11  <h2 id="5502">Using <tt>TList</tt></h2>
  12  <p>
  13  A <tt>TList</tt> object represents a cardinal-indexed array, i.e., an array (object) with the index 0, 1, 2, ...
  14  </p>
  15  <p>
  16  <tt>TList</tt> may be used like a PHP array. For example,
  17  </p>
  18  <com:TTextHighlighter CssClass="source">
  19  $list=new TList; // create a list object
  20  ...
  21  $item=$list[$index];  // read the item at the specified index
  22  $list[]=$item;  // append the item at the end
  23  $list[$index]=$item; // replace the item at the specified index
  24  unset($list[$index]); // remove the item at $index
  25  if(isset($list[$index])) // test if the list has an item at $index
  26  foreach($list as $index=>$item) // traverse each item in the list
  27  </com:TTextHighlighter>
  28  
  29  <p>
  30  To obtain the number of items in the list, use the <tt>Count</tt> property. Note, do not use <tt>count($list)</tt>, as it always returns 1.
  31  </p>
  32  
  33  <p>
  34  In addition, <tt>TList</tt> implements a few commonly used convenient methods for manipulating the data in a list. These include
  35  </p>
  36  <ul>
  37    <li><tt>clear()</tt>: removes all items in the list.</li>
  38    <li><tt>contains()</tt>: tests if the list contains the specified item.</li>
  39    <li><tt>indexOf()</tt>: obtains the zero-based index of the specified item in the list.</li>
  40    <li><tt>toArray()</tt>: returns an array representation of the items in the list.</li>
  41    <li><tt>copyFrom()</tt>: populates the list with data from an array or traversable object (including <tt>TList</tt>). Existing items will be removed first.</li>
  42    <li><tt>mergeWith()</tt>: appends the list with data from an array or traversable object (including <tt>TList</tt>).</li>
  43  </ul>
  44  
  45  <h3 id="5504">Using <tt>TList</tt>-based component properties</h3>
  46  <p>
  47  As aforementioned, many PRADO component properties are based on <tt>TList</tt> or <tt>TList</tt>-derived collection classes. These properties all share the above usages.
  48  </p>
  49  <p>
  50  For example, <tt>TControl</tt> (the base class for all PRADO controls) has a property called <tt>Controls</tt> which represents the collection of child controls. The type of <tt>Controls</tt> is <tt>TControlCollection</tt> which extends <tt>TList</tt>. Therefore, to append a new child control, we can use the following,
  51  </p>
  52  <com:TTextHighlighter CssClass="source">
  53  $control->Controls[]=$newControl;
  54  </com:TTextHighlighter>
  55  <p>
  56  To traverse through the child controls, we can use,
  57  </p>
  58  <com:TTextHighlighter CssClass="source">
  59  foreach($control->Controls as $childControl) ...
  60  </com:TTextHighlighter>
  61  <p>
  62  Another example is the <tt>Items</tt> property, available in list controls, <tt>TRepeater</tt>, <tt>TDataList</tt> and <tt>TDataGrid</tt>. In these controls, the ancestor class of <tt>Items</tt> is <tt>TList</tt>.
  63  </p>
  64  
  65  <h3 id="5505">Extending <tt>TList</tt></h3>
  66  <p>
  67  Often, we want to extend <tt>TList</tt> to perform additional operations for each addition or removal of an item. The only methods that the child class needs to override are <tt>insertAt()</tt> and <tt>removeAt()</tt>. For example, to ensure the list only contains items that are of <tt>TControl</tt> type, we can override <tt>insertAt()</tt> as follows,
  68  </p>
  69  <com:TTextHighlighter CssClass="source">
  70  public function insertAt($index,$item)
  71  {
  72      if($item instanceof TControl)
  73          parent::insertAt($index,$item)
  74      else
  75          throw new Exception('TControl required.');
  76  }
  77  </com:TTextHighlighter>
  78  
  79  
  80  <h2 id="5503">Using <tt>TMap</tt></h2>
  81  <p>
  82  A <tt>TMap</tt> object represents a hash table (or we say string-indexed array).
  83  </p>
  84  <p>
  85  Similar to <tt>TList</tt>, <tt>TMap</tt> may be used like an array,
  86  </p>
  87  <com:TTextHighlighter CssClass="source">
  88  $map=new TMap; // create a map object
  89  ...
  90  $map[$key]=$value; // add a key-value pair
  91  unset($map[$key]); // remove the value with the specified key
  92  if(isset($map[$key])) // if the map contains the key
  93  foreach($map as $key=>$value) // traverse the items in the map
  94  </com:TTextHighlighter>
  95  <p>
  96  The <tt>Count</tt> property gives the number of items in the map while the <tt>Keys</tt> property returns a list of keys used in the map.
  97  </p>
  98  
  99  <p>
 100  The following methods are provided by <tt>TMap</tt> for convenience,
 101  </p>
 102  <ul>
 103    <li><tt>clear()</tt>: removes all items in the map.</li>
 104    <li><tt>contains()</tt>: tests if the map contains the specified key.</li>
 105    <li><tt>toArray()</tt>: returns an array representation of the items in the map.</li>
 106    <li><tt>copyFrom()</tt>: populates the map with data from an array or traversable object (including <tt>TMap</tt>). Existing items will be removed first.</li>
 107    <li><tt>mergeWith()</tt>: appends the map with data from an array or traversable object (including <tt>TMap</tt>).</li>
 108  </ul>
 109  
 110  <h3 id="5506">Using of <tt>TAttributeCollection</tt></h3>
 111  <p>
 112  <tt>TAttributeCollection</tt> is a special class extending from <tt>TMap</tt>. It is mainly used by the <tt>Attributes</tt> property of <tt>TControl</tt>.
 113  </p>
 114  Besides the normal functionalities provided by <tt>TMap</tt>, <tt>TAttributeCollection</tt> allows you to get and set collection items like getting and setting properties. For example,
 115  </p>
 116  <com:TTextHighlighter CssClass="source">
 117  $collection->Label='value'; // equivalent to: $collection['Label']='value';
 118  echo $collection->Label; // equivalent to: echo $collection['Label'];
 119  </com:TTextHighlighter>
 120  <p>
 121  Note, in the above <tt>$collection</tt> does NOT have a <tt>Label</tt> property.
 122  </p>
 123  <p>
 124  Unlike <tt>TMap</tt>, keys in <tt>TAttributeCollection</tt> are case-insensitive. Therefore, <tt>$collection->Label</tt> is equivalent to <tt>$collection->LABEL</tt>.
 125  </p>
 126  <p>
 127  Because of the above new features, when dealing with the <tt>Attributes</tt> property of controls, we may take advantage of the subproperty concept and configure control attribute values in a template as follows,
 128  </p>
 129  <com:TTextHighlighter Language="prado" CssClass="source">
 130  &lt;com:TButton Attributes.onclick="if(!confirm('Are you sure?')) return false;" .../&gt;
 131  </com:TTextHighlighter>
 132  <p>
 133  which adds an attribute named <tt>onclick</tt> to the <tt>TButton</tt> control.
 134  </p>
 135  </com:TContent>