From 6818eb71061580a636831b8e6c0ba8aca2c3420b Mon Sep 17 00:00:00 2001
From: "ctrlaltca@gmail.com" <>
Date: Thu, 2 Jun 2011 16:03:13 +0000
Subject: documentation galore: TCallbackClientSide, TCallbackOptions and
TCallbackClientScript
---
.gitattributes | 9 +++
buildscripts/texbuilder/quickstart/pages.php | 3 +
.../pages/ActiveControls/CallbackClientScript.page | 30 ++++++++
.../pages/ActiveControls/CallbackClientSide.page | 79 ++++++++++++++++++++++
.../pages/ActiveControls/CallbackOptions.page | 52 ++++++++++++++
.../protected/pages/ActiveControls/Home.page | 16 ++---
.../Samples/TCallbackClientScript/Home.page | 39 +++++++++++
.../Samples/TCallbackClientScript/Home.php | 29 ++++++++
.../Samples/TCallbackClientSide/Home.page | 73 ++++++++++++++++++++
.../Samples/TCallbackClientSide/Home.php | 12 ++++
.../Samples/TCallbackOptions/Home.page | 77 +++++++++++++++++++++
.../Samples/TCallbackOptions/Home.php | 12 ++++
.../Web/UI/ActiveControls/TCallbackClientSide.php | 11 ++-
13 files changed, 428 insertions(+), 14 deletions(-)
create mode 100644 demos/quickstart/protected/pages/ActiveControls/CallbackClientScript.page
create mode 100644 demos/quickstart/protected/pages/ActiveControls/CallbackClientSide.page
create mode 100644 demos/quickstart/protected/pages/ActiveControls/CallbackOptions.page
create mode 100644 demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.page
create mode 100644 demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.php
create mode 100644 demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.page
create mode 100644 demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.php
create mode 100644 demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.page
create mode 100644 demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.php
diff --git a/.gitattributes b/.gitattributes
index 6303ca7e..27bf95a3 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1292,6 +1292,9 @@ demos/quickstart/protected/pages/ActiveControls/ActiveRadioButtonList.page -text
demos/quickstart/protected/pages/ActiveControls/ActiveRepeater.page -text
demos/quickstart/protected/pages/ActiveControls/ActiveTextBox.page -text
demos/quickstart/protected/pages/ActiveControls/AutoComplete.page -text
+demos/quickstart/protected/pages/ActiveControls/CallbackClientScript.page -text
+demos/quickstart/protected/pages/ActiveControls/CallbackClientSide.page -text
+demos/quickstart/protected/pages/ActiveControls/CallbackOptions.page -text
demos/quickstart/protected/pages/ActiveControls/DragDrop.page -text
demos/quickstart/protected/pages/ActiveControls/Home.page -text
demos/quickstart/protected/pages/ActiveControls/Introduction.page -text
@@ -1353,6 +1356,12 @@ demos/quickstart/protected/pages/ActiveControls/Samples/TActiveTextBox/Home.page
demos/quickstart/protected/pages/ActiveControls/Samples/TActiveTextBox/Home.php -text
demos/quickstart/protected/pages/ActiveControls/Samples/TAutoComplete/Home.page -text
demos/quickstart/protected/pages/ActiveControls/Samples/TAutoComplete/Home.php -text
+demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.page -text
+demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.php -text
+demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.page -text
+demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.php -text
+demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.page -text
+demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.php -text
demos/quickstart/protected/pages/ActiveControls/Samples/config.xml -text
demos/quickstart/protected/pages/ActiveControls/TActiveButtonClass.png -text
demos/quickstart/protected/pages/ActiveControls/TActiveButtonClass.vsd -text
diff --git a/buildscripts/texbuilder/quickstart/pages.php b/buildscripts/texbuilder/quickstart/pages.php
index 2fe2438f..044ed3c3 100644
--- a/buildscripts/texbuilder/quickstart/pages.php
+++ b/buildscripts/texbuilder/quickstart/pages.php
@@ -125,6 +125,9 @@ $pages['Control Reference : Active Controls (AJAX)'] = array(
'ActiveControls/ActiveRepeater.page',
'ActiveControls/ActiveTextBox.page',
'ActiveControls/AutoComplete.page',
+ 'ActiveControls/CallbackClientScript.page',
+ 'ActiveControls/CallbackClientSide.page',
+ 'ActiveControls/CallbackOptions.page',
'ActiveControls/DragDrop.page');
$pages['Active Control Overview'] = array(
diff --git a/demos/quickstart/protected/pages/ActiveControls/CallbackClientScript.page b/demos/quickstart/protected/pages/ActiveControls/CallbackClientScript.page
new file mode 100644
index 00000000..7ffd2db9
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/CallbackClientScript.page
@@ -0,0 +1,30 @@
+
+
+TCallbackClientScript
+
+
+
+The TCallbackClientScript class provides corresponding methods that can be
+executed on the client-side (i.e. the browser client that is viewing
+the page) during a callback response.
+For a complete list of available client side methods, consult the
+
+
+
+
+The available methods includes setting/clicking input elements, changing Css
+styles, hiding/showing elements, and adding visual effects to elements on the
+page. The client-side methods can be access through the CallbackClient
+property available in TPage.
+
+
+
+For example, to hide "$myTextBox" element during callback response, do:
+
+
+$this->getPage()->getCallbackClient()->hide($myTextBox);
+
+
+
+
+$Id: CallbackClientSide.page -1 $
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/CallbackClientSide.page b/demos/quickstart/protected/pages/ActiveControls/CallbackClientSide.page
new file mode 100644
index 00000000..c8e52585
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/CallbackClientSide.page
@@ -0,0 +1,79 @@
+
+
+TCallbackClientSide
+
+
+
+TCallbackClientSide is used to specify client-side callback request options and client-side event handlers.
+Each active control that inherits from TActiveBaseCallbackControl has a ClientSide property.
+The ClientSide property is an instance TCallbackClientSide containing the actual options and event handlers
+that are used by the client-side when that control is making a callback request.
+The following example demonstrates the toggling of a "loading" indicator when the client-side is making a callback request.
+
+
+
+<com:TClientScript PradoScripts="effects" />
+Loading...
+
+<com:TActiveButton
+ Text="Click Me"
+ OnCallback="button_callback"
+ ActiveControl.CallbackParameter="value" >
+ <prop:ClientSide
+ OnLoading="Element.show('callback_status')"
+ OnComplete="Element.hide('callback_status')" />
+</com:TActiveButton>
+
+
+Events
+
+
+The following client side events are executing in order if the callback
+request and response are send and received successfuly.
+
+
+
+ - onPreDispatch: executed before a request is dispatched;
+ - onUninitialized: executed when callback request is uninitialized;
+ - onLoading* : executed when callback request is initiated;
+ - onLoaded* : executed when callback request begins;
+ - onInteractive: executed when callback request is in progress;
+ - onComplete: executed when callback response returns;
+ - onSuccess executed when callback request returns and is successful;
+ - onFailure executed when callback request fails (only for communication errors);
+ - onException raised when callback request fails due to request/response errors.
+
+
+
+* Note that theses 2 events are not fired correctly by Opera. To make
+ them work in this browser, Prado will fire them just after onPreDispatch.
+
+
+
+In a general way, onUninitialized, onLoading, onLoaded and onInteractive events
+are not implemented consistently in all browsers. When cross browser compatibility is
+needed, it is best to avoid use them.
+
The OnSuccess and OnFailure events are raised when the
+response is returned. A successful request/response will raise
+OnSuccess event otherwise OnFailure will be raised.
+
+
+Properties
+
+
+The following properties can be used to change the way the callback request is performed.
+
+
+
+ - PostState: true to collect the form inputs and post them during callback (default: true);
+ - RequestTimeOut The request timeout in milliseconds (default: 30000, i.e. 30 seconds);
+ - HasPriority true to ensure that the callback request will be sent
+ immediately and will abort existing prioritized requests. It does not affect
+ callbacks that are not prioritized (default: true);
+ - EnablePageStateUpdate enable the callback response to enable the
+ viewstate update. This will automatically set HasPriority to true when enabled. (default: true).
+
+
+
+
+$Id$
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/CallbackOptions.page b/demos/quickstart/protected/pages/ActiveControls/CallbackOptions.page
new file mode 100644
index 00000000..184c116c
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/CallbackOptions.page
@@ -0,0 +1,52 @@
+
+
+TCallbackOptions
+
+
+
+TCallbackOptions allows a common set of callback client-side options
+to be attached to one or more active controls.
+This can be useful if a lot of active controls on the same page are sharing the same callback client-side options.
+Instead of specifying the same set of options again and again inside each control, these can be written once
+inside a TCallbackOptions; this TCallbackOptions can be then attached to each control using the
+ActiveControl.CallbackOptions property. For a full list of assignable properties, please check the
+TCallbackClientSide documentation.
+
+
+
+The typical scenario of use for a TCallbackOptions is a page where a lot of active controls needs to
+pause the user interaction with a "Please wait" style message until callback completion.
+First create a single TCallbackOptions control, assign it an ID and the the needed properties:
+
+
+
+<com:TCallbackOptions
+ ID="MyOptions"
+ ClientSide.OnLoading="... kindly inform the user that he should wait ..."
+ ClientSide.OnComplete="... callback completed, ready to serve the user again ..."
+/>
+
+
+
+Then, share this set of options to one or more active controls; each control will follow them:
+
+
+
+<com:TActiveButton
+ Text="simple button"
+ OnCallback="..."
+ ActiveControl.CallbackOptions="MyOptions"
+ ...
+/>
+
+<com:TActiveCheckBox
+ Text="simple checkbox"
+ OnCallback="..."
+ ActiveControl.CallbackOptions="MyOptions"
+ ...
+/>
+
+
+
+
+$Id$
\ 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 a658aa16..7834cc1d 100644
--- a/demos/quickstart/protected/pages/ActiveControls/Home.page
+++ b/demos/quickstart/protected/pages/ActiveControls/Home.page
@@ -97,11 +97,6 @@ TActiveButton control. See also the later part of the TCallbackOptions
- callback options such as OnLoading client-side event handlers.
-
-
Active List Controls
@@ -387,14 +382,19 @@ realize the active controls.
- * TCallbackClientScript
+ TCallbackClientScript
methods to manipulate the client-side HTML elements, also includes methods
to invoke javascript Effects on HTML elements.
- * TCallbackClientSide
- common client-side callback request options, and client-side event handlers.
+ TCallbackClientSide
+ is used to specify client-side callback request options and client-side event handlers.
+
+
+
+ TCallbackOptions
+ allows a common set of callback client-side options to be attached to one or more active controls.
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.page b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.page
new file mode 100644
index 00000000..49baa47c
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.page
@@ -0,0 +1,39 @@
+
+TCallbackClientScript Samples
+
+
+ Choose an action from the list and click the button; the server-side php code will get the selected value and
+ force the execution of some clientside js code in the callback response.
+
+
+Actions
+
+
+
+
+
+
+
+
+
+
+Results
+
+
+
+ Checkbox 1: |
+ |
+
+
+ Label 1: |
+ |
+
+
+ TextBox 1: |
+ |
+
+
+
+
+
+$Id: Home.page -1 $
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.php b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.php
new file mode 100644
index 00000000..500d7987
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientScript/Home.php
@@ -0,0 +1,29 @@
+radio1->SelectedValue)
+ {
+ case 1:
+ $this->getCallbackClient()->evaluateScript("");
+ break;
+ case 2:
+ $this->getCallbackClient()->check($this->check1, !$this->check1->Checked);
+ break;
+ case 3:
+ $this->getCallbackClient()->hide($this->label1);
+ break;
+ case 4:
+ $this->getCallbackClient()->show($this->label1);
+ break;
+ case 5:
+ $this->getCallbackClient()->focus($this->txt1);
+ break;
+ }
+ }
+}
+
+?>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.page b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.page
new file mode 100644
index 00000000..4540dd91
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.page
@@ -0,0 +1,73 @@
+
+TCallbackClientSide Samples
+
+
+
+
+A callback button with attached client side options:
+ |
+
+
+
+ please wait 5 seconds for the callback to complete...
+callback completed!
+ |
+
+
+A callback button logging all callback events (5 seconds delay):
+ |
+
+
+
+
+ |
+
+
+A callback with RequestTimeout="3000" (3 seconds). Since the callback will take 5 seconds to complete, the clientside will timeout.
+This will cause a "missing page state" error; note that the callback is not considered failed, since no
+connection error has occured.
+ |
+
+
+
+
+ |
+
+
+
+
+
+$Id: Home.page -1 $
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.php b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.php
new file mode 100644
index 00000000..8dd794fe
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackClientSide/Home.php
@@ -0,0 +1,12 @@
+
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.page b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.page
new file mode 100644
index 00000000..9cc2f155
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.page
@@ -0,0 +1,77 @@
+
+TCallbackOptions Samples
+
+
+
+
+A callback button with attached client side options:
+ |
+
+
+ please wait 5 seconds for the callback to complete...
+callback completed!
+ |
+
+
+Same example as before, but this time interacting with another Prado control:
+ |
+
+
+
+ |
+
+
+The same TCallbackOptions can be shared among different controls, even of different types:
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+
+
+$Id$
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.php b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.php
new file mode 100644
index 00000000..6f101107
--- /dev/null
+++ b/demos/quickstart/protected/pages/ActiveControls/Samples/TCallbackOptions/Home.php
@@ -0,0 +1,12 @@
+
\ No newline at end of file
diff --git a/framework/Web/UI/ActiveControls/TCallbackClientSide.php b/framework/Web/UI/ActiveControls/TCallbackClientSide.php
index 31b806c3..cc3b9449 100644
--- a/framework/Web/UI/ActiveControls/TCallbackClientSide.php
+++ b/framework/Web/UI/ActiveControls/TCallbackClientSide.php
@@ -22,6 +22,9 @@
* - onLoaded* executed when callback request begins.
* - onInteractive executed when callback request is in progress.
* - onCompleteexecuted when callback response returns.
+ * - onSuccess executed when callback request returns and is successful.
+ * - onFailure executed when callback request returns and fails.
+ * - onException raised when callback request fails due to request/response errors.
*
* * Note that theses 2 events are not fired correctly by Opera. To make
* them work in this browser, Prado will fire them just after onPreDispatch.
@@ -29,22 +32,18 @@
* In a general way, onUninitialized, onLoading, onLoaded and onInteractive events
* are not implemented consistently in all browsers.When cross browser compatibility is
* needed, it is best to avoid use them
- *
+ *
* The OnSuccess and OnFailure events are raised when the
* response is returned. A successful request/response will raise
* OnSuccess event otherwise OnFailure will be raised.
*
- * - onSuccess executed when callback request returns and is successful.
- * - onFailure executed when callback request returns and fails.
- * - onException raised when callback request fails due to request/response errors.
- *
* - PostState true to collect the form inputs and post them during callback, default is true.
* - RequestTimeOut The request timeout in milliseconds.
* - HasPriority true to ensure that the callback request will be sent
* immediately and will abort existing prioritized requests. It does not affect
* callbacks that are not prioritized.
* - EnablePageStateUpdate enable the callback response to enable the
- * viewstate update. This will automatically set HasPrority to true when enabled.
+ * viewstate update. This will automatically set HasPriority to true when enabled.
*
* @author Wei Zhuo
* @version $Id$
--
cgit v1.2.3