Subversion-Projekte lars-tiefland.prado

<?php

/**

 * TBaseActiveControl and TBaseActiveCallbackControl class file.

 *

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

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

 * @copyright Copyright © 2005-2008 PradoSoft

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

 * @version $Id: TBaseActiveControl.php 2564 2008-11-11 21:56:02Z carlgmathisen $

 * @package System.Web.UI.ActiveControls

 */

Prado::using('System.Web.UI.ActiveControls.TCallbackClientSide');

/**

 * 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 $Id: TBaseActiveControl.php 2564 2008-11-11 21:56:02Z carlgmathisen $

 * @package System.Web.UI.ActiveControls

 * @since 3.1

 */

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;

		if(!is_null($value))

			$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 TMap active control options

	 */

	protected function getOptions()

	{

		return $this->_options;

	}

	/**

	 * @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;

	}

	/**

	 * @param boolean true to allow fine grain callback updates.

	 */

	public function setEnableUpdate($value)

	{

		$this->setOption('EnableUpdate', TPropertyValue::ensureBoolean($value), true);

	}

	/**

	 * @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 and

	 * the page is not loading post data.

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

	 * client-side contents.

	 */

	public function canUpdateClientSide()

	{

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

				&& $this->getPage()->getIsLoadingPostData() == false

				&& $this->getPage()->getIsCallback()

				&& $this->getEnableUpdate();

	}

}

/**

 * 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 $Id: TBaseActiveControl.php 2564 2008-11-11 21:56:02Z carlgmathisen $

 * @package System.Web.UI.ActiveControls

 * @since 3.1

 */

class TBaseActiveCallbackControl extends TBaseActiveControl

{

	/**

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

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

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

	 * @return TCallbackClientSide client-side callback options.

	 */

	public function getClientSide()

	{

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

		{

			$client = $this->createClientSide();

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

		}

		return $client;

	}

	/**

	 * Sets the client side options. Can only be set when client side is null.

	 * @param TCallbackClientSide client side options.

	 */

	public function setClientSide($client)

	{

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

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

		else

			throw new TConfigurationException(

				'active_controls_client_side_exists', $this->getControl()->getID());

	}

	/**

	 * @return TCallbackClientSide callback client-side options.

	 */

	protected function createClientSide()

	{

		return new TCallbackClientSide;

	}

	/**

	 * Sets default callback options. Takes the ID of a TCallbackOptions

	 * component to duplicate the client-side

	 * options for this control. The {@link getClientSide ClientSide}

	 * subproperties has precendent over the CallbackOptions property.

	 * @param string ID of a TCallbackOptions control from which ClientSide

	 * options are cloned.

	 */

	public function setCallbackOptions($value)

	{

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

	}

	/**

	 * @return string ID of a TCallbackOptions control from which ClientSide

	 * options are duplicated.

	 */

	public function getCallbackOptions()

	{

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

	}

	/**

	 * Returns an array of default callback client-side options. The default options

	 * are obtained from the client-side options of a TCallbackOptions control with

	 * ID specified by {@link setCallbackOptionsID CallbackOptionsID}.

	 * @return array list of default callback client-side options.

	 */

	protected function getDefaultClientSideOptions()

	{

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

		{

			if(($pos=strrpos($id,'.'))!==false)

			{

				$control=$this->getControl()->getSubProperty(substr($id,0,$pos));

				$newid=substr($id,$pos+1);

				if ($control!==null)

					$control=$control->findControl($newid);

			}

			else

			{

				 $control=$this->getControl()->findControl($id);

			}

			if($control instanceof TCallbackOptions)

				return $control->getClientSide()->getOptions()->toArray();

			else

				throw new TConfigurationException('callback_invalid_callback_options_ID', $id);

		}

		return array();

	}

	/**

	 * @return boolean whether callback event trigger by this button will cause

	 * input validation, default is true

	 */

	public function getCausesValidation()

	{

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

	}

	/**

	 * @param boolean whether callback event trigger by this button will cause

	 * input validation

	 */

	public function setCausesValidation($value)

	{

		$this->setOption('CausesValidation',TPropertyValue::ensureBoolean($value),true);

	}

	/**

	 * @return string the group of validators which the button causes validation

	 * upon callback

	 */

	public function getValidationGroup()

	{

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

	}

	/**

	 * @param string the group of validators which the button causes validation

	 * upon callback

	 */

	public function setValidationGroup($value)

	{

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

	}

	/**

	 * @return boolean whether to perform validation if the callback is

	 * requested.

	 */

	public function canCauseValidation()

	{

		if($this->getCausesValidation())

		{

			$group=$this->getValidationGroup();

			return $this->getPage()->getValidators($group)->getCount()>0;

		}

		else

			return false;

	}

	/**

	 * @param mixed callback parameter value.

	 */

	public function setCallbackParameter($value)

	{

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

	}

	/**

	 * @return mixed callback parameter value.

	 */

	public function getCallbackParameter()

	{

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

	}

	/**

	 * @return array list of callback javascript options.

	 */

	protected function getClientSideOptions()

	{

		$default = $this->getDefaultClientSideOptions();

		$options = array_merge($default,$this->getClientSide()->getOptions()->toArray());

		$validate = $this->getCausesValidation();

		$options['CausesValidation']= $validate ? '' : false;

		$options['ValidationGroup']=$this->getValidationGroup();

		$options['CallbackParameter'] = $this->getCallbackParameter();

		return $options;

	}

	/**

	 * 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();

		//remove true as default to save bytes

		if($options['CausesValidation']===true)

			$options['CausesValidation']='';

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

	}

	/**

	 * Returns the javascript callback request instance. To invoke a callback

	 * request for this control call the <tt>dispatch()</tt> method on the

	 * request instance. Example code in javascript

	 * <code>

	 *   var request = <%= $this->mycallback->ActiveControl->Javascript %>;

	 *   request.setParameter('hello');

	 *   request.dispatch(); //make the callback request.

	 * </code>

	 *

	 * Alternatively,

	 * <code>

	 * //dispatches immediately

	 * Prado.Callback("<%= $this->mycallback->UniqueID %>",

	 *    $this->mycallback->ActiveControl->JsCallbackOptions);

	 * </code>

	 * @return string javascript client-side callback request object (javascript

	 * code)

	 */

	public function getJavascript()

	{

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

		return $client->getCallbackReference($this->getControl(),$this->getClientSideOptions());

	}

	/**

	 * @param string callback requestion options as javascript code.

	 */

	public function getJsCallbackOptions()

	{

		return TJavaScript::encode($this->getClientSideOptions());

	}

}