added a warning to TClientScript; refs #401

1 files changed, 14 insertions, 0 deletions

diff --git a/framework/Web/UI/WebControls/TClientScript.php b/framework/Web/UI/WebControls/TClientScript.php
index 4736df0e..0679aa74 100644
--- a/framework/Web/UI/WebControls/TClientScript.php
+++ b/framework/Web/UI/WebControls/TClientScript.php
@@ -31,6 +31,20 @@
  * Contents within TClientScript will be treated as javascript code and will be

  * rendered in place.

  *

+ * Since Prado 3.2, TClientScript gained the ability to render itself on ajax 

+ * callbacks. This means that every variable or function declared in javascript

+ * code will be available to the page.

+ *

+ * Beware that when rendered on normal (postback) or ajax callbacks, some

+ * javascript code won't behave in the same way. 

+ * When rendered as part of a normal/postback response, scripts will execute instantly 

+ * where they are in the page and in a synchronous fashion.

+ * Instead, when they are rendered as part of a callback response,

+ * they will be executed when all DOM modifications are complete and any dynamic

+ * script file includes are loaded, out-of-band and practically all blocks at once,

+ * regardless of where they actually occour in the original template/markup code.

+ * This can potentially hurt compatibility and graceful fallback.

+ *

  * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

  * @version $Id$

  * @package System.Web.UI.WebControls