Added tutorial page for collections.

5 files changed, 141 insertions, 13 deletions

diff --git a/.gitattributes b/.gitattributes
index 73f553c3..fc3e6cd1 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -123,6 +123,7 @@ demos/quickstart/protected/index/quickstart/deletable -text
 demos/quickstart/protected/index/quickstart/segments -text
 demos/quickstart/protected/pages/Advanced/Assets.page -text
 demos/quickstart/protected/pages/Advanced/Auth.page -text
+demos/quickstart/protected/pages/Advanced/Collections.page -text
 demos/quickstart/protected/pages/Advanced/Error.page -text
 demos/quickstart/protected/pages/Advanced/I18N.page -text
 demos/quickstart/protected/pages/Advanced/Logging.page -text
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 @@
+<com:TContent ID="body" >

+

+<h1>Collections</h1>

+<p>

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

+</p>

+<p>

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

+</p>

+

+<h2>Using <tt>TList</tt></h2>

+<p>

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

+</p>

+<p>

+<tt>TList</tt> may be used like a PHP array. For example,

+</p>

+<com:TTextHighlighter CssClass="source">

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

+</com:TTextHighlighter>

+

+<p>

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

+</p>

+

+<p>

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

+</p>

+<ul>

+  <li><tt>clear()</tt>: removes all items in the list.</li>

+  <li><tt>contains()</tt>: tests if the list contains the specified item.</li>

+  <li><tt>indexOf()</tt>: obtains the zero-based index of the specified item in the list.</li>

+  <li><tt>toArray()</tt>: returns an array representation of the items in the list.</li>

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

+  <li><tt>mergeWith()</tt>: appends the list with data from an array or traversable object (including <tt>TList</tt>).</li>

+</ul>

+

+<h3>Using <tt>TList</tt>-based component properties</h3>

+<p>

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

+</p>

+<p>

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

+</p>

+<com:TTextHighlighter CssClass="source">

+$control->Controls[]=$newControl;

+</com:TTextHighlighter>

+<p>

+To traverse through the child controls, we can use,

+</p>

+<com:TTextHighlighter CssClass="source">

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

+</com:TTextHighlighter>

+<p>

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

+</p>

+

+<h3>Extending <tt>TList</tt></h3>

+<p>

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

+</p>

+<com:TTextHighlighter CssClass="source">

+public function insertAt($index,$item)

+{

+    if($item instanceof TControl)

+        parent::insertAt($index,$item)

+    else

+        throw new Exception('TControl required.');

+}

+</com:TTextHighlighter>

+

+

+<h2>Using <tt>TMap</tt></h2>

+<p>

+A <tt>TMap</tt> object represents a hash table (or we say string-indexed array).

+</p>

+<p>

+Similar to <tt>TList</tt>, <tt>TMap</tt> may be used like an array,

+</p>

+<com:TTextHighlighter CssClass="source">

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

+</com:TTextHighlighter>

+<p>

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

+</p>

+

+<p>

+The following methods are provided by <tt>TMap</tt> for convenience,

+</p>

+<ul>

+  <li><tt>clear()</tt>: removes all items in the map.</li>

+  <li><tt>contains()</tt>: tests if the map contains the specified key.</li>

+  <li><tt>toArray()</tt>: returns an array representation of the items in the map.</li>

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

+  <li><tt>mergeWith()</tt>: appends the map with data from an array or traversable object (including <tt>TMap</tt>).</li>

+</ul>

+

+<h3>Using of <tt>TAttributeCollection</tt></h3>

+<p>

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

+</p>

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

+</p>

+<com:TTextHighlighter CssClass="source">

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

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

+</com:TTextHighlighter>

+<p>

+Note, in the above <tt>$collection</tt> does NOT have a <tt>Label</tt> property.

+</p>

+<p>

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

+</p>

+<p>

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

+</p>

+<com:TTextHighlighter Language="prado" CssClass="source">

+&lt;com:TButton Attributes.onclick="if(!confirm('Are you sure?')) return false;" .../&gt;

+</com:TTextHighlighter>

+<p>

+which adds an attribute named <tt>onclick</tt> to the <tt>TButton</tt> control.

+</p>

+</com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/themes/PradoSoft/style.css b/demos/quickstart/themes/PradoSoft/style.css
index 3bf73c80..0fed7813 100644
--- a/demos/quickstart/themes/PradoSoft/style.css
+++ b/demos/quickstart/themes/PradoSoft/style.css
@@ -90,7 +90,7 @@ a
 

 #toc {

 	background-color: #F3F3F3;

-	width:200px;

+	width:220px;

 	padding:0px 10px 0px 10px;

 }

 

@@ -138,18 +138,15 @@ a
 {

     list-style: none;

     margin: 0px;

-    padding: 0px;

+    padding: 5px;

+	padding-left: 15px;

+	border-bottom: 1px dotted #D8D8D8;

 }

 

 .topic a {

-    display: block;

 	color:#4F811A;

-	padding: 5px;

-	padding-left: 20px;

-	height: 12px;

 	font-size: 8pt;

 	text-decoration: none;

-	border-bottom: 1px dotted #D8D8D8;

 }

 

 .topic a:hover {

diff --git a/framework/Collections/TList.php b/framework/Collections/TList.php
index 244eab0f..5b27a02e 100644
--- a/framework/Collections/TList.php
+++ b/framework/Collections/TList.php
@@ -30,7 +30,7 @@
  * to determine the number of items in the list.

  *

  * To extend TList by doing additional operations with each addition or removal

- * operations, override {@link insertAt()}, and {@link removeAt()}.

+ * operation, override {@link insertAt()}, and {@link removeAt()}.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

diff --git a/framework/Collections/TMap.php b/framework/Collections/TMap.php
index 85da4f3c..28508e1d 100644
--- a/framework/Collections/TMap.php
+++ b/framework/Collections/TMap.php
@@ -28,11 +28,6 @@
  * Note, count($map) will always return 1. You should use {@link getCount()}

  * to determine the number of items in the map.

  *

- * To extend TMap by doing additional operations with each added or removed item,

- * you can override {@link addedItem} and {@link removedItem}.

- * You can also override {@link canAddItem} and {@link canRemoveItem} to

- * control whether to add or remove a particular item.

- *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

  * @package System.Collections