updated QS pages.

3 files changed, 77 insertions, 29 deletions

diff --git a/demos/quickstart/protected/pages/Configurations/Templates1.page b/demos/quickstart/protected/pages/Configurations/Templates1.page
index 34ffc975..9a71d6a5 100644
--- a/demos/quickstart/protected/pages/Configurations/Templates1.page
+++ b/demos/quickstart/protected/pages/Configurations/Templates1.page
@@ -34,19 +34,24 @@ Note, property names and event names are all case-insensitive, while component t
 Also note, initial values for properties whose name ends with <tt>Template</tt> are specially processed. In particular, the initial values are parsed as <tt>TTemplate</tt> objects. The <tt>ItemTemplate</tt> property of the <tt>TRepeater</tt> control is such an example.

 </p>

 <p id="180173" class="block-content">

-To deal conveniently with properties taking take big trunk of initial data, the following property initialization tag is introduced,

+To facilitate initializing properties with big trunk of data, the following property initialization tag is introduced. It is equivalent to <tt>...PropertyName="PropertyValue"...</tt> in every aspect. Property initialization tags must be directly enclosed between the corresponding opening and closing component tag.

+</p>

 <com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180074">

 &lt;prop:PropertyName&gt;

 PropertyValue

 &lt;/prop:PropertyName&gt;

 </com:TTextHighlighter>

-It is equivalent to <tt>...PropertyName="PropertyValue"...</tt> in every aspect. Property initialization tags must be directly enclosed between the corresponding opening and closing component tag.

+<p>

+Since version 3.1.0, the property initialization tag can also be used to initialize a set of subproperties who share the same parent property. For example, the following is equivalent to <tt>HeaderStyle.BackColor="black"</tt> and <tt>HeaderStyle.ForeColor="red"</tt>.

 </p>

+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180075">

+&lt;prop:HeaderStyle BackColor="black" ForeColor="red" />

+</com:TTextHighlighter>

 

 <h3 id="1505">Component IDs</h3>

 <p id="180174" class="block-content">

 When specified in templates, component <tt>ID</tt> property has special meaning in addition to its normal property definition. A component tag specified with an ID value in template will register the corresponding component to the template owner control. The component can thus be directly accessed from the template control with its ID value. For example, in <tt>Home</tt> page's template, the following component tag

-<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180075">

+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180076">

 &lt;com:TTextBox ID="TextBox" Text="First Name" />

 </com:TTextHighlighter>

 makes it possible to get the textbox object in code using <tt>$page->TextBox</tt>.

@@ -55,7 +60,7 @@ makes it possible to get the textbox object in code using <tt>$page->TextBox</tt
 <a name="tct"></a>

 <h2 id="1503">Template Control Tags</h2>

 A template control tag is used to configure the initial property values of the control owning the template. Its format is as follows,

-<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180076">

+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180077">

 &lt;%@ PropertyName="PropertyValue" ... %&gt;

 </com:TTextHighlighter>

 Like in component tags, <tt>PropertyName</tt> is case-insensitive and can be a property or subproperty name.

@@ -72,7 +77,7 @@ Template control tag is optional in a template. Each template can contain at mos
 <p id="180177" class="block-content">

 Comment tags are used to put in a template developer comments that will not display to end-users. Contents enclosed within a comment tag will be treated as raw text strings and PRADO will not attempt to parse them. Comment tags cannot be used within property values. The format of comment tags is as follows,

 </p>

-<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180077">

+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180078">

 &lt;!--

 Comments INVISIBLE to end-users

 ---&gt;

@@ -84,7 +89,7 @@ The new comment tag <tt>&lt;!-- ... ---&gt;</tt> has been introduced since PRADO
 <p id="180178" class="block-content">

 Since version 3.0.5, PRADO starts to support external template inclusion. This is accomplished via include tags, where external template files are specified in namespace format and their file name must be terminated as <tt>.tpl</tt>.

 </p>

-<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180078">

+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180079">

 &lt;%include path.to.templateFile %&gt;

 </com:TTextHighlighter>

 

diff --git a/demos/quickstart/protected/pages/Controls/Repeater.page b/demos/quickstart/protected/pages/Controls/Repeater.page
index cc642c5a..69c6cdba 100644
--- a/demos/quickstart/protected/pages/Controls/Repeater.page
+++ b/demos/quickstart/protected/pages/Controls/Repeater.page
@@ -1,20 +1,39 @@
 <com:TContent ID="body" >

 

 <h1 id="5301">TRepeater</h1>

+

 <p id="600400" class="block-content">

-TRepeater displays its content defined in templates repeatedly based on the given data specified by the <tt>DataSource</tt> or <tt>DataSourceID</tt> property. The repeated contents can be retrieved from the <tt>Items</tt> property. Each item is created by instantiating a template and each is a child control of the repeater.

+TRepeater displays its content repeatedly based on the data fetched from <tt>DataSource</tt>. The repeated contents in TRepeater are called <i>items</i> which are controls accessible through <tt>Items</tt> property. When <tt>dataBind()</tt> is invoked, TRepeater creates an item for each row of data and binds the data row to the item. Optionally, a repeater can have a header, a footer and/or separators between items.

 </p>

+

 <p id="600401" class="block-content">

-Like normal control templates, the repeater templates can contain static text, controls and special tags, which after instantiation, become child contents of the corresponding item. TRepeater defines five templates for different purposes,

+The layout of the repeated contents are specified by inline templates. In particular, repeater items, header, footer, etc. are being instantiated with the corresponding templates when data is being bound to the repeater.

+</p>

+

+<p id="600402" class="block-content">

+Since v3.1.0, the layout can also be specified by <i>renderers</i>. A renderer is a control class that can be instantiated as repeater items, header, etc. A renderer can thus be viewed as an external template (in fact, it can also be non-templated controls). A renderer can be any control class. If implemented with one of the following interfaces, a renderer will be initialized with additional properties relevant to the repeater items:

 </p>

+

 <ul id="u1" class="block-content">

-  <li><tt>HeaderTemplate</tt> - the template used for displaying content at the beginning of a repeater;</li>

-  <li><tt>FooterTemplate</tt> - the template used for displaying content at the end of a repeater;</li>

-  <li><tt>ItemTemplate</tt> - the template used for displaying every repeater item. If <tt>AlternatingItemTemplate</tt> is also defined, <tt>ItemTemplate</tt> will be used for displaying item 1, 3, 5, etc.</li>

-  <li><tt>AlternatingItemTemplate</tt> - the template used for displaying every alternating repeater item (i.e., item 2, 4, 6, etc.)</li>

-  <li><tt>SeparatorTemplate</tt> - the template used for displaying content between items.</li>

+<li><tt>IDataRenderer</tt> - the <tt>Data</tt> property will be set as the row of the data bound to the repeater item. Many PRADO controls implement this interface, such as <tt>TLabel</tt>, <tt>TTextBox</tt>, etc.</li>

+<li><tt>IItemDataRenderer</tt> - the <tt>ItemIndex</tt> property will be set as the zero-based index of the item in the repeater item collection, and the <tt>ItemType</tt> property as the item's type (such as <tt>TListItemType::Item</tt>). As a convenient base class, <tt>TRepeaterItemRenderer</tt> implements <tt>IDataItemRenderer</tt> and can have an associated template because it extends from <tt>TTemplateControl</tt>.</li>

 </ul>

-<p id="600402" class="block-content">

+

+

+<p id="600403" class="block-content">

+The following properties are used to specify different types of template and renderer for a repeater. If an item type is defined with both a template and a renderer, the latter takes precedence.

+</p>

+<ul id="u2" class="block-content">

+<li><tt>ItemTemplate</tt>, <tt>ItemRenderer</tt> - for each repeated row of data.</li>

+<li><tt>AlternatingItemTemplate</tt>, <tt>AlternatingItemRenderer</tt>: for each alternating row of data. If not set, <tt>ItemTemplate</tt> or <tt>ItemRenderer</tt> will be used instead, respectively.</li>

+<li><tt>HeaderTemplate</tt>, <tt>HeaderRenderer</tt> - for the repeater header.</li>

+<li><tt>FooterTemplate</tt>, <tt>FooterRenderer</tt> - for the repeater footer.</li>

+<li><tt>SeparatorTemplate</tt>, <tt>SeparatorRenderer</tt> - for content to be displayed between items.</li>

+<li><tt>EmptyTemplate</tt>, <tt>EmptyRenderer</tt> - used when data bound to the repeater is empty.</li>

+</ul>

+

+

+<p id="600404" class="block-content">

 To populate data into the repeater items, set <tt>DataSource</tt> to a valid data object, such as array, <tt>TList</tt>, <tt>TMap</tt>, or a database table, and then call <tt>dataBind()</tt> for the repeater. That is,

 </p>

 <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_600125">

@@ -28,32 +47,54 @@ class MyPage extends TPage {
     }

 }

 </com:TTextHighlighter>

-<p id="600403" class="block-content">

-Normally, you only need to do this when the page containing the repeater is initially requested. In postbacks, TRepeater is smart enough to remember the previous state, i.e., contents populated with datasource information.The following sample displays tabular data using TRepeater.

+

+<p id="600405" class="block-content">

+When <tt>dataBind()</tt> is called, TRepeater undergoes the following lifecycles for each row of data:

 </p>

-<p id="600404" class="block-content">

-TRepeater provides several events to facilitate manipulation of its items,

+

+<ol id="u3" class="block-content">

+<li>create item based on templates or renderers</li>

+<li>set the row of data to the item</li>

+<li>raise an <tt>OnItemCreated</tt> event</li>

+<li>add the item as a child control</li>

+<li>call <tt>dataBind()</tt> of the item</li>

+<li>raise an <tt>OnItemDataBound</tt> event</li>

+</ol>

+

+<p id="600406" class="block-content">

+Normally, you only need to bind the data to repeater when the page containing the repeater is initially requested. When the page is post back, the repeater will restore automatically all its contents, including items, header, footer and separators. However, the data row associated with each item will not be recovered and thus become null.

 </p>

-<ul id="u2" class="block-content">

-  <li><tt>OnItemCreated</tt> - raised each time an item is newly created. When the event is raised, data and child controls are both available for the new item.</li>

-  <li><tt>OnItemDataBound</tt> - raised each time an item just completes databinding. When the event is raised, data and child controls are both available for the item, and the item has finished databindings of itself and all its child controls.</li>

-  <li><tt>OnItemCommand</tt> - raised when a child control of some item (such as a <tt>TButton</tt>) raises an <tt>OnCommand</tt> event.</li>

+

+<p id="600407" class="block-content">

+To access the repeater item data in postbacks, use one of the following ways:

+</p>

+<ul id="u4" class="block-content">

+<li>Use <tt>DataKeys</tt> to obtain the data key associated with the specified repeater item and use the key to fetch the corresponding data from some persistent storage such as DB. </li>

+<li>Save the whole dataset in viewstate, which will restore the dataset automatically upon postback. Be aware though, if the size of your dataset is big, your page size will become big. Some complex data may also have serializing problem if saved in viewstate.</li>

 </ul>

-<p id="600405" class="block-content">

+

+

+<p id="600408" class="block-content">

+TRepeater raises an <tt>OnItemCommand</tt> event whenever a button control within some repeater item raises a <tt>OnCommand</tt> event. Therefore,

+you can handle all sorts of <tt>OnCommand</tt> event in a central place by

+writing an event handler for <tt>OnItemCommand</tt>.

+</p>

+

+<p id="600409" class="block-content">

 The following example shows how to use TRepeater to display tabular data.

 </p>

 <com:RunBar PagePath="Controls.Samples.TRepeater.Sample1" />

-<p id="600406" class="block-content">

+<p id="600410" class="block-content">

 TRepeater can be used in more complex situations. As an example, we show in the following how to use nested repeaters, i.e., repeater in repeater. This is commonly seen in presenting master-detail data. To use a repeater within another repeater, for an item for the outer repeater is created, we need to set the detail data source for the inner repeater. This can be achieved by responding to the <tt>OnItemDataBound</tt> event of the outer repeater. An <tt>OnItemDataBound</tt> event is raised each time an outer repeater item completes databinding. In the following example, we exploit another event of repeater called <tt>OnItemCreated</tt>, which is raised each time a repeater item (and its content) is newly created. We respond to this event by setting different background colors for repeater items to achieve alternating item background display. This saves us from writing an <tt>AlternatingItemTemplate</tt> for the repeaters.

 </p>

 <com:RunBar PagePath="Controls.Samples.TRepeater.Sample2" />

-<p id="600407" class="block-content">

+<p id="600411" class="block-content">

 Besides displaying data, TRepeater can also be used to collect data from users. Validation controls can be placed in TRepeater templates to verify that user inputs are valid.

 </p>

-<p id="600408" class="block-content">

+<p id="600412" class="block-content">

 The <a href="../composer/index.php">PRADO component composer</a> demo is a good example of such usage. It uses a repeater to collect the component property and event definitions. Users can also delete or adjust the order of the properties and events, which is implemented by responding to the <tt>OnItemCommand</tt> event of repeater.

 </p>

-<p id="600409" class="block-content">

+<p id="600413" class="block-content">

 See in the following yet another example showing how to use repeater to collect user inputs.

 </p>

 <com:RunBar PagePath="Controls.Samples.TRepeater.Sample3" />

diff --git a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
index 781eb0fa..ca1f361f 100644
--- a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
+++ b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
@@ -14,8 +14,10 @@ This page summarizes the main new features that are introduced in each PRADO rel
 <li>Layered database support - </li>

 <li>New controls, modules and services - TSoapService, TOutputCache, TSessionPageStatePersister, TFeedService, TJsonService, cache dependency classes, TXmlTransform

 </li>

-<li>Configure subproperties in a group</li>

-<li>Item renderer feature for <tt>TRepeater</tt>, <tt>TDataList</tt> and <tt>TDataGrid</tt></li>

+

+<li>New template syntax facilitating <a href="?page=Configurations.Templates1">subproperty configuration</a>.</li>

+

+<li>Introduction of renderer concept - renderer enables reusing item templates that are commonly found in <tt>TRepeater</tt>, <tt>TDataList</tt> and <tt>TDataGrid</tt>, and makes the configuration on these controls much cleaner. For more details about renders, see the updated tutorials on <a href="?page=Controls.Repeater"><tt>TRepeater</tt></a>, <a href="?page=Controls.DataList"><tt>TDataList</tt></a> and <a href="?page=Controls.DataGrid"><tt>TDataGrid</tt></a>.</li>

 </ul>

 

 <div class="last-modified">$Id$</div>