Update active controls. Add comments. Add THttpResponseAdapter

1 files changed, 109 insertions, 19 deletions

diff --git a/framework/Web/UI/ActiveControls/TBaseActiveControl.php b/framework/Web/UI/ActiveControls/TBaseActiveControl.php
index d2f1ef57..13d953c8 100644
--- a/framework/Web/UI/ActiveControls/TBaseActiveControl.php
+++ b/framework/Web/UI/ActiveControls/TBaseActiveControl.php
@@ -1,18 +1,59 @@
 <?php

-/*

- * Created on 13/05/2006

+/**

+ * TBaseActiveControl and TBaseActiveCallbackControl class file.

+ *

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

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 2005 PradoSoft

+ * @license http://www.pradosoft.com/license/

+ * @version $Revision: $  $Date: $

+ * @package System.Web.UI.ActiveControls

+ */

+

+/**

+ * TBaseActiveControl class provided additional basic property for every

+ * active control. An instance of TBaseActiveControl or its decendent

+ * TBaseActiveCallbackControl is created by {@link TActiveControlAdapter::getBaseActiveControl()}

+ * method.

+ * 

+ * The {@link setEnableUpdate EnableUpdate} property determines wether the active

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

+ * response returns. 

+ * 

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

+ * @version $Revision: $  $Date: $

+ * @package System.Web.UI.ActiveControls

+ * @since 3.0

  */

 class TBaseActiveControl extends TComponent

 {

+	/**

+	 * @TMap map of active control options.

+	 */

 	private $_options;

+	/**

+	 * @TControl attached control.

+	 */

 	private $_control;

 

+	/**

+	 * Constructor. Attach a base active control to an active control instance.

+	 * @param TControl active control

+	 */

 	public function __construct($control)

 	{

 		$this->_control = $control;

 		$this->_options = new TMap;

 	}

 

+	/** 

+	 * Sets a named options with a value. Options are used to store and retrive

+	 * named values for the base active controls.

+	 * @param string option name.

+	 * @param mixed new value.

+	 * @param mixed default value.

+	 * @return mixed options value.

+	 */

 	protected function setOption($name,$value,$default=null)

 	{

 		$value = is_null($value) ? $default : $value;

@@ -20,17 +61,30 @@ class TBaseActiveControl extends TComponent
 			$this->_options->add($name,$value);

 	}

 

+	/** 

+	 * Gets an option named value. Options are used to store and retrive

+	 * named values for the base active controls.

+	 * @param string option name.

+	 * @param mixed default value.

+	 * @return mixed options value.

+	 */

 	protected function getOption($name,$default=null)

 	{

 		$item = $this->_options->itemAt($name);

 		return is_null($item) ? $default : $item;

 	}

 

+	/**

+	 * @return TPage the page containing the attached control.

+	 */

 	protected function getPage()

 	{

 		return $this->_control->getPage();

 	}

 

+	/**

+	 * @return TControl the attached control.

+	 */

 	protected function getControl()

 	{

 		return $this->_control;

@@ -44,14 +98,21 @@ class TBaseActiveControl extends TComponent
 		$this->setOption('EnableUpdate', TPropertyValue::ensureBoolean($value), true);

 	}

 

-	/**

-	 * @return true to allow fine grain callback updates.

+	/** 

+	 * @return boolean true to allow fine grain callback updates.

 	 */

 	public function getEnableUpdate()

 	{

 		return $this->getOption('EnableUpdate', true);

 	}

 

+	/** 

+	 * Returns true if callback response is allowed to update the browser contents.

+	 * Is is true if the control is initilized, and is a callback request and 

+	 * the {@link setEnableUpdate EnabledUpdate} property is true.

+	 * @return boolean true if the callback response is allowed update 

+	 * client-side contents. 

+	 */

 	public function canUpdateClientSide()

 	{

 		return 	$this->getControl()->getIsInitialized()

@@ -60,21 +121,44 @@ class TBaseActiveControl extends TComponent
 	}

 }

 

-

+/**

+ * TBaseActiveCallbackControl is a common set of options and functionality for

+ * active controls that can perform callback requests. 

+ * 

+ * The properties of TBaseActiveCallbackControl can be accessed and changed from

+ * each individual active controls' {@link getActiveControl ActiveControl} 

+ * property.

+ * 

+ * The following example to set the validation group property of a TCallback component.

+ * <code>

+ * 	<com:TCallback ActiveControl.ValidationGroup="group1" ... />

+ * </code>

+ * 

+ * Additional client-side options and events can be set using the 

+ * {@link getClientSide ClientSide} property. The following example to show 

+ * an alert box when a TCallback component response returns successfully.

+ * <code>

+ * 	<com:TCallback Active.Control.ClientSide.OnSuccess="alert('ok!')" ... />

+ * </code>

+ *

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

+ * @version $Revision: $  Fri Jun 16 08:40:43 EST 2006 $

+ * @package System.Web.UI.ActiveControls

+ * @since 3.0

+ */

 class TBaseActiveCallbackControl extends TBaseActiveControl

 {

 	/**

 	 * Callback client-side options can be set by setting the properties of

-	 * the ClientSide property. E.g. <com:TCallback ClientSide.OnSuccess="..." />

-	 * See {@link TCallbackClientSideOptions} for details on the properties of

-	 * ClientSide.

+	 * the ClientSide property. E.g. <com:TCallback ActiveControl.ClientSide.OnSuccess="..." />

+	 * See {@link TCallbackClientSideOptions} for details on the properties of ClientSide.

 	 * @return TCallbackClientSideOptions client-side callback options.

 	 */

 	public function getClientSide()

 	{

 		if(is_null($client = $this->getOption('ClientSide')))

 		{

-			$client = $this->createClientSide();

+			$client = $this->createClientSideOptions();

 			$this->setOption('ClientSide', $client);

 		}

 		return $client;

@@ -83,9 +167,9 @@ class TBaseActiveCallbackControl extends TBaseActiveControl
 	/**

 	 * @return TCallbackClientSideOptions callback client-side options.

 	 */

-	protected function createClientSide()

+	protected function createClientSideOptions()

 	{

-		if(($id=$this->getCallbackOptions())!==''

+		if(($id=$this->getCallbackOptionID())!=='' 

 			&& ($control=$this->getControl()->findControl($id))!==null)

 		{

 			if($control instanceof TCallbackOptions)

@@ -101,7 +185,7 @@ class TBaseActiveCallbackControl extends TBaseActiveControl
 	 * @param string ID of a TCallbackOptions control from which ClientSide

 	 * options are cloned.

 	 */

-	public function setCallbackOptions($value)

+	public function setCallbackOptionID($value)

 	{

 		$this->setOption('CallbackOptions', $value, '');

 	}

@@ -110,7 +194,7 @@ class TBaseActiveCallbackControl extends TBaseActiveControl
 	 * @return string ID of a TCallbackOptions control from which ClientSide

 	 * options are cloned.

 	 */

-	public function getCallbackOptions()

+	public function getCallbackOptionID()

 	{

 		return $this->getOption('CallbackOptions', '');

 	}

@@ -178,17 +262,23 @@ class TBaseActiveCallbackControl extends TBaseActiveControl
 		return $options;

 	}

 

-	public function registerCallbackClientScript($options=null)

+	/**

+	 * Registers the callback control javascript code. Client-side options are

+	 * merged and passed to the javascript code. This method should be called by

+	 * Active component developers wanting to register the javascript to initialize

+	 * the active component with additional options offered by the 

+	 * {@link getClientSide ClientSide} property.

+	 * @param string client side javascript class name.

+	 * @param array additional callback options.

+	 */

+	public function registerCallbackClientScript($class,$options=null)

 	{

 		$cs = $this->getPage()->getClientScript();

 		if(is_array($options))

 			$options = array_merge($this->getClientSideOptions(),$options);

 		else

-			$options = $this->getClientSideOptions();

-		// TODO (xue):

-		// We need explicitly specify what js class is to be used

-		// to avoid problem that may occur in extended child class

-		$cs->registerCallbackControl('Prado.WebUI.'.get_class($this->getControl()), $options);

+			$options = $this->getClientSideOptions();			

+		$cs->registerCallbackControl($class, $options);

 	}

 

 	/**