documentation updates: TCallback, TEventTriggeredCallback, TValueTriggeredCallback, TTimeTriggeredCallback

13 files changed, 328 insertions, 22 deletions

diff --git a/demos/quickstart/protected/pages/ActiveControls/Callback.page b/demos/quickstart/protected/pages/ActiveControls/Callback.page
new file mode 100644
index 00000000..d37eb614
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Callback.page
@@ -0,0 +1,34 @@
+<com:TContent ID="body" >

+

+<h1>TCallback</h1>

+<com:DocLink ClassPath="System.Web.UI.ActiveControls.TCallback" />

+

+<p class="block-content">

+<tt>TCallback</tt> provides a basic callback handler that can be invoked from the

+client side by using the javascript ojbect obtained from the

+<tt>ActiveControl.Javascript</tt> property.

+You can set the <tt>CallbackParameter</tt> property from javascript directly on

+the object returned by <tt>ActiveControl.Javascript</tt>.

+Once you are ready, you can call the <tt>dispatch()<tt> method on the object to

+execute the callback.

+The server-side event <tt>OnCallback</tt> is raised when a callback is requested made.

+</p>

+

+<p class="block-content">

+Example usage:

+</p>

+<com:TTextHighlighter Language="text" CssClass="source block-content" >

+&lt;com:TCallback ID="callback1" OnCallback="callback1_Requested" /&gt;

+&lt;script type="text/javascript"&gt;

+  function do_callback1()

+  {

+    var request = &lt;%= $this->callback1->ActiveControl->Javascript %&gt;;

+    request.dispatch();

+  }

+&lt;/script&gt;

+&lt;div onclick="do_callback1()">Click Me!&lt;/div&gt;

+</com:TTextHighlighter>

+

+<com:RunBar PagePath="ActiveControls.Samples.TCallback.Home" />

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/EventTriggeredCallback.page b/demos/quickstart/protected/pages/ActiveControls/EventTriggeredCallback.page
new file mode 100644
index 00000000..170fa295
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/EventTriggeredCallback.page
@@ -0,0 +1,15 @@
+<com:TContent ID="body" >

+

+<h1>TEventTriggeredCallback</h1>

+<com:DocLink ClassPath="System.Web.UI.ActiveControls.TEventTriggeredCallback" />

+

+<p class="block-content">

+<tt>TEventTriggeredCallback</tt> triggers a new callback request when a particular <tt>EventName</tt>

+on a control with ID given by <tt>ControlID</tt> is raised.

+The default action of the event on the client-side can be prevented when

+<tt>PreventDefaultAction</tt> is set to true.

+</p>

+

+<com:RunBar PagePath="ActiveControls.Samples.TEventTriggeredCallback.Home" />

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Home.page b/demos/quickstart/protected/pages/ActiveControls/Home.page
index 7834cc1d..bb74c4bf 100644
--- a/demos/quickstart/protected/pages/ActiveControls/Home.page
+++ b/demos/quickstart/protected/pages/ActiveControls/Home.page
@@ -159,12 +159,12 @@ TActiveButton</a> control. See also the later part of the <a href="?page=Tutoria
 	</li>

 

 	<li>

-	* <a href="?page=ActiveControls.Callback">TCallback</a>

+	<a href="?page=ActiveControls.Callback">TCallback</a>

 	a generic control that can perform callback requests.

 	</li>

 

 	<li>

-	* <a href="?page=ActiveControls.EventTriggeredCallback">TEventTriggeredCallback</a>

+	<a href="?page=ActiveControls.EventTriggeredCallback">TEventTriggeredCallback</a>

 	triggers a callback request based on HTML DOM events.

 	</li>

 

@@ -174,12 +174,12 @@ TActiveButton</a> control. See also the later part of the <a href="?page=Tutoria
 	</li>

 

 	<li>

-	* <a href="?page=ActiveControls.TimeTriggeredCallback">TTimeTriggeredCallback</a>

+	<a href="?page=ActiveControls.TimeTriggeredCallback">TTimeTriggeredCallback</a>

 	triggers a callback request based on time elapsed.

 	</li>

 

 	<li>

-	* <a href="?page=ActiveControls.ValueTriggeredCallback">TValueTriggeredCallback</a>

+	<a href="?page=ActiveControls.ValueTriggeredCallback">TValueTriggeredCallback</a>

 	monitors (using a timer) an attribute of an HTML element and triggers a callback request

 	when the attribute value changes.

 	</li>

@@ -355,32 +355,72 @@ if Javascript was disabled on the client's browser.</p>
   

 </table>

 

-<h2 id="128036">Active Control Infrastructure Classes</h2>

+<h2 id="128036">Active Control Basic Infrastructure Classes</h2>

 <p id="640427" class="block-content">The following classes provide the basic infrastructure classes required to

-realize the active controls.</p>

+realize the active controls. They can be useful to develop new active controls, but Prado users tipically don't need

+to use them.</p>

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

 	<li>

-	* <a href="?page=ActiveControls.ActiveControlAdapter">TActiveControlAdapter</a>

-	tracks the viewstate values of the control and update differences of the client-side HTML

-	element attributes.

+	<h3>TActiveControlAdapter</h3>

+	<com:DocLink ClassPath="System.Web.UI.ActiveControls.TActiveControlAdapter" />

+	<p class="block-content">

+		<tt>TActiveControlAdapter</tt> customizes the parent TControl class for active control classes.

+		It tracks changes in the viewstate values of the control and update

+		differences of the client-side HTML element attributes.

+	</p>

+	</li>

+

+	<li>

+	<h3>TActiveListControlAdapter</h3>

+	<com:DocLink ClassPath="System.Web.UI.ActiveControls.TActiveListControlAdapter" />

+	<p class="block-content">

+		<tt>TActiveListControlAdapter</tt> allows the adapted list controls to change the selections

+		on the client-side during a callback request.

+	</p>

 	</li>

 

 	<li>

-	* <a href="?page=ActiveControls.ActiveListControlAdapter">TActiveListControlAdapter</a>

-	allows the adapted list controls to change the selections on the client-side during

-	a callback request.

+	<h3>TActivePageAdapter</h3>

+	<com:DocLink ClassPath="System.Web.UI.ActiveControls.TActivePageAdapter" />

+	<p class="block-content">

+		<tt>TActivePageAdapter</tt> process the page life-cycle for callback requests.

+	</p>

 	</li>

 

 	<li>

-	* <a href="?page=ActiveControls.ActivePageAdapter">TActivePageAdapter</a>

-	process the page life-cycle for callback requests.

+	<h3>TBaseActiveControl</h3>

+	<com:DocLink ClassPath="System.Web.UI.ActiveControls.TBaseActiveControl" />

+	<p class="block-content">

+		<tt>TBaseActiveControl</tt> class provided additional basic properties common for every

+		active control. An instance of <tt>TBaseActiveControl</tt> or its decendent

+		<tt>TBaseActiveCallbackControl</tt> is created by <tt>TActiveControlAdapter::getBaseActiveControl()</tt>

+		method.

+		The <tt>EnableUpdate</tt> property determines wether the active

+		control is allowed to update the contents of the client-side when the callback

+		response returns.

+	</p>

 	</li>

 

 	<li>

-	* <a href="?page=ActiveControls.BaseActiveControl">TBaseActiveControl</a>

-	common active control methods and options.

+	<h3>TCallbackResponseAdapter</h3>

+	<com:DocLink ClassPath="System.Web.UI.ActiveControls.TCallbackResponseAdapter" />

+	<p class="block-content">

+		<tt>TCallbackResponseAdapter</tt> alters the <tt>THttpResponse</tt>'s outputs.

+		A <tt>TCallbackResponseWriter</tt> is used instead of the <tt>TTextWrite</tt> when

+		<tt>createHtmlWriter</tt> is called. Each call to createHtmlWriter will create

+		a new <tt>TCallbackResponseWriter</tt>. When <tt>flushContent()</tt> is called each

+		instance of <tt>TCallbackResponseWriter</tt>'s content is flushed.

+		The callback response data can be set using the <tt>ResponseData</tt> property.

+	</p>

 	</li>

 

+</ul>

+

+<h2>Active Control Infrastructure Advanced Classes</h2>

+<p class="block-content">The following classes provide advanced properties and events needed to realize the active controls.

+A Prado user can use them to customize active controls behaviour and interact directly with the client side during a callback.

+</p>

+<ul class="block-content">

 	<li>

 	<a href="?page=ActiveControls.CallbackClientScript">TCallbackClientScript</a>

 	methods to manipulate the client-side HTML elements, also includes methods

@@ -396,12 +436,6 @@ realize the active controls.</p>
 	<a href="?page=ActiveControls.CallbackOptions">TCallbackOptions</a>

 	allows a common set of callback client-side options to be attached to one or more active controls.

 	</li>

-

-	<li>

-	* <a href="?page=ActiveControls.CallbackResponseAdapter">TCallbackResponseAdapter</a>

-	HTTP response for callback requests.

-	</li>

-

 </ul>

 

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

diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallback/Home.page b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallback/Home.page
new file mode 100644
index 00000000..55ced11e
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallback/Home.page
@@ -0,0 +1,57 @@
+<com:TContent ID="body">

+

+<h1>TCallback Samples</h1>

+

+<table class="sampletable">

+

+<tr><td class="samplenote">

+An active label text being set as the result of a callback:

+</td><td class="sampleaction">

+

+<com:TCallback ID="callback1" OnCallback="callback1_Requested" />

+<script type="text/javascript">

+  function do_callback1()

+  {

+    var request = <%= $this->callback1->ActiveControl->Javascript %>;

+    request.dispatch();

+  }

+</script>

+<div onclick="do_callback1()" style="background-color:red;border: 1px solid black">Click Me!</div>

+<br/><com:TActiveLabel Text="This is a label" ID="label1"

+/>

+

+<br/><com:TActiveButton

+	Text="reset example"

+	OnClick="buttonClicked"

+/>

+</td></tr>

+

+<tr><td class="samplenote">

+A TCallback with a 3-items array as parameter.

+The first parameter is defined in the onclick() attribute of the red div;

+The second parameter is defined in the body of the javascript function;

+The third parameter is taken from the textbox;

+</td><td class="sampleaction">

+

+<com:TCallback ID="callback2" OnCallback="callback2_Requested" />

+<script type="text/javascript">

+  function do_callback2(param1)

+  {

+    var request = <%= $this->callback2->ActiveControl->Javascript %>;

+    var param2 = 'value 2';

+    var param3 = $('<%= $this->txt1->ClientID %>').value;

+    request.setCallbackParameter({'Param1':param1, 'Param2':param2, 'Param3':param3});

+    request.dispatch();

+  }

+</script>

+TextBox for third parameter: <com:TTextBox ID="txt1" text="value 3"/>

+<div onclick="do_callback2('value 1')" style="background-color:red;border: 1px solid black">Click Me!</div>

+<br/>Parameter 1 is <com:TActiveLabel Text="" ID="labelParam1" />

+<br/>Parameter 2 is <com:TActiveLabel Text="" ID="labelParam2" />

+<br/>Parameter 3 is <com:TActiveLabel Text="" ID="labelParam3" />

+</td></tr>

+

+

+</table>

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallback/Home.php b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallback/Home.php
new file mode 100644
index 00000000..e7f39967
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallback/Home.php
@@ -0,0 +1,24 @@
+<?php
+
+class Home extends TPage
+{
+	public function callback1_Requested($sender,$param)
+	{
+		$this->label1->Text="You clicked the div, didn't you?";
+	}
+
+	public function buttonClicked($sender,$param)
+	{
+		$this->label1->Text="This is a label";
+	}
+
+	public function callback2_Requested($sender,$param)
+	{
+		$parameters=$param->CallbackParameter;
+		$this->labelParam1->Text = THttpUtility::htmlEncode($parameters->Param1);
+		$this->labelParam2->Text = THttpUtility::htmlEncode($parameters->Param2);
+		$this->labelParam3->Text = THttpUtility::htmlEncode($parameters->Param3);
+	}
+}
+
+?>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TEventTriggeredCallback/Home.page b/demos/quickstart/protected/pages/ActiveControls/Samples/TEventTriggeredCallback/Home.page
new file mode 100644
index 00000000..e5293f87
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TEventTriggeredCallback/Home.page
@@ -0,0 +1,18 @@
+<com:TContent ID="body">

+

+<h1>TEventTriggeredCallback Samples</h1>

+

+<table class="sampletable">

+

+<tr><td class="samplenote">

+  A callback will be executed when the textbox receives and loses focus

+</td><td class="sampleaction">

+  <com:TTextBox ID="txt1" />

+  <com:TEventTriggeredCallback ControlID="txt1" EventName="focus" OnCallback="txtFocused" />

+  <com:TEventTriggeredCallback ControlID="txt1" EventName="blur" OnCallback="txtBlurred" />

+  <com:TActiveLabel ID="label1" />

+</td></tr>

+

+</table>

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TEventTriggeredCallback/Home.php b/demos/quickstart/protected/pages/ActiveControls/Samples/TEventTriggeredCallback/Home.php
new file mode 100644
index 00000000..8d92e4a3
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TEventTriggeredCallback/Home.php
@@ -0,0 +1,16 @@
+<?php
+
+class Home extends TPage
+{
+	public function txtFocused($sender,$param)
+	{
+		$this->label1->Text="Textbox focused";
+	}
+
+	public function txtBlurred($sender,$param)
+	{
+		$this->label1->Text="Textbox lost focus";
+	}
+}
+
+?>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TTimeTriggeredCallback/Home.page b/demos/quickstart/protected/pages/ActiveControls/Samples/TTimeTriggeredCallback/Home.page
new file mode 100644
index 00000000..822be2b4
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TTimeTriggeredCallback/Home.page
@@ -0,0 +1,24 @@
+<com:TContent ID="body">

+

+<h1>TTimeTriggeredCallback Samples</h1>

+

+<table class="sampletable">

+

+<tr><td class="samplenote">

+A timer updating a label with the current time every 5 seconds:

+</td><td class="sampleaction">

+<com:TTimeTriggeredCallback ID="time1" Interval="5" OnCallback="timercallback" />

+<com:TActiveButton

+	Text="start timer"

+	OnClick="startClicked"

+/>

+<com:TActiveButton

+	Text="stop timer"

+	OnClick="stopClicked"

+/>

+<com:TActiveLabel ID="label1" />

+</td></tr>

+

+</table>

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TTimeTriggeredCallback/Home.php b/demos/quickstart/protected/pages/ActiveControls/Samples/TTimeTriggeredCallback/Home.php
new file mode 100644
index 00000000..6c44c8c1
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TTimeTriggeredCallback/Home.php
@@ -0,0 +1,22 @@
+<?php
+
+class Home extends TPage
+{
+	public function startClicked($sender,$param)
+	{
+		$this->time1->startTimer();
+	}
+
+	public function stopClicked($sender,$param)
+	{
+		$this->time1->stopTimer();
+	}
+
+	public function timerCallback($sender,$param)
+	{
+		$this->label1->Text="Current time is ".date('H:i:s');
+	}
+
+}
+
+?>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TValueTriggeredCallback/Home.page b/demos/quickstart/protected/pages/ActiveControls/Samples/TValueTriggeredCallback/Home.page
new file mode 100644
index 00000000..50edf6ed
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TValueTriggeredCallback/Home.page
@@ -0,0 +1,17 @@
+<com:TContent ID="body">

+

+<h1>TValueTriggeredCallback Samples</h1>

+

+<table class="sampletable">

+

+<tr><td class="samplenote">

+  A callback will be executed when the textbox text changes

+</td><td class="sampleaction">

+  <com:TTextBox ID="txt1" />

+  <com:TValueTriggeredCallback ControlID="txt1" PropertyName="value" OnCallback="checkTxtValue" />

+  <com:TActiveLabel ID="label1" />

+</td></tr>

+

+</table>

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TValueTriggeredCallback/Home.php b/demos/quickstart/protected/pages/ActiveControls/Samples/TValueTriggeredCallback/Home.php
new file mode 100644
index 00000000..7e2a8b20
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TValueTriggeredCallback/Home.php
@@ -0,0 +1,11 @@
+<?php
+
+class Home extends TPage
+{
+	public function checkTxtValue($sender,$param)
+	{
+		$this->label1->Text=date("[H:i:s]")." Textbox changed";
+	}
+}
+
+?>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/TimeTriggeredCallback.page b/demos/quickstart/protected/pages/ActiveControls/TimeTriggeredCallback.page
new file mode 100644
index 00000000..3239f931
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/TimeTriggeredCallback.page
@@ -0,0 +1,16 @@
+<com:TContent ID="body" >

+

+<h1>TTimeTriggeredCallback</h1>

+<com:DocLink ClassPath="System.Web.UI.ActiveControls.TTimeTriggeredCallback" />

+

+<p class="block-content">

+<tt>TTimeTriggeredCallback</tt> sends callback request every <tt>Interval</tt> seconds.

+Upon each callback request, the <tt>OnCallback</tt> event is raised.

+The timer can be started by calling <tt>startTimer()</tt> and stopped using

+<tt>stopTimer()</tt>. The timer can be automatically started when

+<tt>StartTimerOnLoad</tt> is true.

+</p>

+

+<com:RunBar PagePath="ActiveControls.Samples.TTimeTriggeredCallback.Home" />

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/ValueTriggeredCallback.page b/demos/quickstart/protected/pages/ActiveControls/ValueTriggeredCallback.page
new file mode 100644
index 00000000..c05d6a20
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/ValueTriggeredCallback.page
@@ -0,0 +1,18 @@
+<com:TContent ID="body" >

+

+<h1>TValueTriggeredCallback</h1>

+<com:DocLink ClassPath="System.Web.UI.ActiveControls.TValueTriggeredCallback" />

+

+<p class="block-content">

+<tt>TValueTriggeredCallback</tt> observes the value with <tt>PropertyName</tt> of a

+control with <tt>ControlID</tt>. Changes to the observed

+property value will trigger a new callback request. The property value is checked

+for changes every <tt>Interval</tt> seconds.

+A <tt>DecayRate</tt> can be set to increase the polling

+interval linearly if no changes are observed. Once a change is

+observed, the polling interval is reset to the original value.

+</p>

+

+<com:RunBar PagePath="ActiveControls.Samples.TValueTriggeredCallback.Home" />

+

+<div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file