Issue#36: Refactored TRatingList/TActiveRatingList, and added some docs.

1 files changed, 47 insertions, 296 deletions

diff --git a/framework/Web/UI/ActiveControls/TActiveRatingList.php b/framework/Web/UI/ActiveControls/TActiveRatingList.php
index c8da9295..473ca06a 100644
--- a/framework/Web/UI/ActiveControls/TActiveRatingList.php
+++ b/framework/Web/UI/ActiveControls/TActiveRatingList.php
@@ -3,8 +3,9 @@
  * TActiveRatingList class file.

  *

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

+ * @author Bradley Booms <bradley[dot]booms[at]gmail[dot]com>

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

- * @copyright Copyright &copy; 2005-2008 PradoSoft
+ * @copyright Copyright &copy; 2005-2008 PradoSoft

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

  * @version $Id$

  * @package System.Web.UI.ActiveControls

@@ -13,107 +14,85 @@
 /**

  * TActiveRatingList Class

  *

- * Displays clickable images that represent a TActiveRadioButtonList

+ * Displays clickable images that represent a TRadioButtonList

  *

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

+ * @author Bradley Booms <bradley[dot]booms[at]gmail[dot]com>

  * @version $Id$

  * @package System.Web.UI.ActiveControls

  * @since 3.1

  */

-class TActiveRatingList extends TActiveRadioButtonList

+class TActiveRatingList extends TRatingList implements IActiveControl, ICallbackEventHandler

 {

-	const SCRIPT_PATH = 'prado/activeratings';

-

-	/**

-	 * @var array list of published rating images.

-	 */

-	private $_ratingImages = array();

-

 	/**

-	 * Sets the default repeat direction to horizontal.

+	 * Creates a new callback control, sets the adapter to

+	 * TActiveListControlAdapter. If you override this class, be sure to set the

+	 * adapter appropriately by, for example, by calling this constructor.

 	 */

 	public function __construct()

 	{

+		$this->setAdapter(new TActiveListControlAdapter($this));

+		$this->setAutoPostBack(true);

 		parent::__construct();

-		$this->setRepeatDirection(TRepeatDirection::Horizontal);

-	}

-

-	/**

-	 * @return boolean whether the items in the column can be edited. Defaults to false.

-	 */

-	public function getReadOnly()

-	{

-		return $this->getViewState('ReadOnly',false);

 	}

 

 	/**

-	 * @param boolean whether the items in the column can be edited

+	 * @return TBaseActiveCallbackControl standard callback control options.

 	 */

-	public function setReadOnly($value)

+	public function getActiveControl()

 	{

-		$this->setViewState('ReadOnly',TPropertyValue::ensureBoolean($value),false);

+		return $this->getAdapter()->getBaseActiveControl();

 	}

 

 	/**

-	 * The repeat layout must be Table.

-	 * @param string repeat layout type

-	 * @throws TInvaliddataValueException when repeat layout is not Table.

+	 * @return TCallbackClientSide client side request options.

 	 */

-	public function setRepeatLayout($value)

+	public function getClientSide()

 	{

-		if($value!==TRepeatLayout::Table)

-			throw new TInvalidDataValueException('ratinglist_table_layout_only');

-		else

-			parent::setRepeatLayout($value);

+		return $this->getAdapter()->getBaseActiveControl()->getClientSide();

 	}

 

 	/**

-	 * @return float rating value.

+	 * Raises the callback event. This method is required by {@link

+	 * ICallbackEventHandler} interface.

+	 * This method is mainly used by framework and control developers.

+	 * @param TCallbackEventParameter the event parameter

 	 */

-	public function getRating()

+ 	public function raiseCallbackEvent($param)

 	{

-		return $this->getViewState('Rating',0.0);

+		$this->onCallback($param);

 	}

 

 	/**

-	 * @param float rating value, also sets the selected Index

+	 * This method is invoked when a callback is requested. The method raises

+	 * 'OnCallback' event to fire up the event handlers. If you override this

+	 * method, be sure to call the parent implementation so that the event

+	 * handler can be invoked.

+	 * @param TCallbackEventParameter event parameter to be passed to the event handlers

 	 */

-	public function setRating($value)

+	public function onCallback($param)

 	{

-		$rating = TPropertyValue::ensureFloat($value);

-		$this->setViewState('Rating', $rating);

-		$canUpdate = $this->getActiveControl()->getEnableUpdate();

-		$this->getActiveControl()->setEnableUpdate(false);

-		parent::setSelectedIndex($this->getRatingIndex($rating));

-		$this->getActiveControl()->setEnableUpdate($canUpdate);

-		if($this->getActiveControl()->canUpdateClientSide())

-			$this->callClientFunction('setRating',$rating);

+		$this->raiseEvent('OnCallback', $this, $param);

 	}

 

 	/**

-	 * @param float rating value

-	 * @return int rating as integer

+	 * @param boolean whether the items in the column can be edited

 	 */

-	protected function getRatingIndex($rating)

+	public function setReadOnly($value)

 	{

-		$interval = $this->getHalfRatingInterval();

-		$base = intval($rating)-1;

-		$remainder = $rating-$base-1;

-		return $remainder > $interval[1] ? $base+1 : $base;

+		parent::setReadOnly($value);

+		$value = $this->getReadOnly();

+		$this->callClientFunction('setReadOnly',$value);

 	}

 

 	/**

-	 * @param int change the rating selection index

+	 * @param float rating value, also sets the selected Index

 	 */

-	public function setSelectedIndex($value)

+	public function setRating($value)

 	{

-		$value = TPropertyValue::ensureInteger($value);

-		$canUpdate = $this->getActiveControl()->getEnableUpdate();

-		$this->getActiveControl()->setEnableUpdate(false);

-		parent::setSelectedIndex($value);

-		$this->getActiveControl()->setEnableUpdate($canUpdate);

-		if($this->getActiveControl()->canUpdateClientSide())

-			$this->callClientFunction('setRating',$value+1);

+		parent::setRating($value);

+		$value = $this->getRating();

+		$this->callClientFunction('setRating',$value);

 	}

 

 	/**

@@ -123,250 +102,22 @@ class TActiveRatingList extends TActiveRadioButtonList
 	 */

 	protected function callClientFunction($func,$value)

 	{

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

-		$code = $this->getClientClassName().'.'.$func;

-		$client->callClientFunction($code,array($this,$value));

-	}

-

-	/**

-	 * @return string control or html element ID for displaying a caption.

-	 */

-	public function getCaptionID()

-	{

-		return $this->getViewState('CaptionID', '');

-	}

-

-	/**

-	 * @param string control or html element ID for displaying a caption.

-	 */

-	public function setCaptionID($value)

-	{

-		$this->setViewState('CaptionID', $value, '');

-	}

-

-	protected function getCaptionControl()

-	{

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

-		{

-			if($control=$this->getParent()->findControl($id))

-				return $control;

-		}

-		throw new TInvalidDataValueException(

-			'ratinglist_invalid_caption_id',$id,$this->getID());

-	}

-

-	public function setCaption($value)

-	{

-		$this->getCaptionControl()->setText($value);

-		if($this->getActiveControl()->canUpdateClientSide())

-			$this->callClientFunction('setCaption',$value);

-	}

-

-	public function getCaption()

-	{

-		return $this->getCaptionControl()->getText();

-	}

-

-	/**

-	 * @param boolean true to enable the rating to be changed.

-	 */

-	public function setEnabled($value)

-	{

-		$value = TPropertyValue::ensureBoolean($value);

-		parent::setEnabled($value);

 		if($this->getActiveControl()->canUpdateClientSide())

-			$this->callClientFunction('setEnabled',$value);

-	}

-

-	/**

-	 * @param string set the rating style, default is "default"

-	 */

-	public function setRatingStyle($value)

-	{

-	   $this->setViewState('RatingStyle', $value, 'default');

-	}

-

-	/**

-	 * @return TActiveRatingListStyle current rating style

-	 */

-	public function getRatingStyle()

-	{

-	   return $this->getViewState('RatingStyle', 'default');

-	}

-

-	/**

-	 * Sets the interval such that those rating values within the interval

-	 * will be considered as a half star rating.

-	 * @param array rating display half value interval, default is array(0.3, 0.7);

-	 */

-	public function setHalfRatingInterval($value)

-	{

-		$this->setViewState('HalfRating',

-				TPropertyValue::ensureArray($value), array(0.3, 0.7));

-	}

-

-	/**

-	 * @return array rating display half value interval, default is array(0.3, 0.7);

-	 */

-	public function getHalfRatingInterval()

-	{

-		return $this->getViewState('HalfRating', array(0.3, 0.7));

-	}

-

-	/**

-	 * @return string rating style css class name.

-	 */

-	protected function getRatingStyleCssClass()

-	{

-		return 'TActiveRatingList_'.$this->getRatingStyle();

-	}

-

-	/**

-	 * @return array list of post back options.

-	 */

-	protected function getPostBackOptions()

-	{

-		$options = parent::getPostBackOptions();

-		$options['Style'] = $this->getRatingStyleCssClass();

-		$options['CaptionID'] = $this->getCaptionControlID();

-		$options['SelectedIndex'] = $this->getSelectedIndex();

-		$options['Rating'] = $this->getRating();

-		$options['HalfRating'] = $this->getHalfRatingInterval();

-		return $options;

-	}

-

-	/**

-	 * Registers the javascript code for initializing the active control

-	 * only if {@link setReadOnly ReadOnly} property is false.

-	 */

-	protected function renderClientControlScript($writer)

-	{

-		if($this->getReadOnly()===false)

-			parent::renderClientControlScript($writer);

-	}

-

-	/**

-	 * @return string find the client ID of the caption control.

-	 */

-	protected function getCaptionControlID()

-	{

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

 		{

-			if($control=$this->getParent()->findControl($id))

-			{

-				if($control->getVisible(true))

-					return $control->getClientID();

-			}

-			else

-				return $id;

+			$client = $this->getPage()->getCallbackClient();

+			$code = parent::getClientClassName().'.'.$func;

+			$client->callClientFunction($code,array($this,$value));

 		}

-		return '';

 	}

 

 	/**

-	 * @param string asset file in the self::SCRIPT_PATH directory.

-	 * @return string asset file url.

+	 * @param string caption text

 	 */

-	protected function getAssetUrl($file='')

-	{

-		$base = $this->getPage()->getClientScript()->getPradoScriptAssetUrl();

-		return $base.'/'.self::SCRIPT_PATH.'/'.$file;

-	}

-

-	/**

-	 * @param string rating style name

-	 * @return string URL of the css style file

-	 */

-	protected function publishRatingListStyle($style)

-	{

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

-		$url = $this->getAssetUrl($style.'.css');

-		if(!$cs->isStyleSheetFileRegistered($url))

-			$cs->registerStyleSheetFile($url, $url);

-		return $url;

-	}

-

-	/**

-	 * @param string rating style name

-	 * @param string rating image file extension, default is '.gif'

-	 * @return array URL of publish the rating images

-	 */

-	protected function publishRatingListImages($style, $fileExt='.gif')

-	{

-		$types = array('blank', 'selected', 'half', 'combined');

-		$files = array();

-		foreach($types as $type)

-			$files[$type] = $this->getAssetUrl("{$style}_{$type}{$fileExt}");

-		return $files;

-	}

-

-	/**

-	 * Add rating style class name to the class attribute

-	 * when {@link setReadOnly ReadOnly} property is true and when the

-	 * {@link setCssClass CssClass} property is empty.

-	 * @param THtmlWriter renderer

-	 */

-	public function render($writer)

-	{

-		if($this->getReadOnly())

-			$writer->addAttribute('class', $this->getRatingStyleCssClass());

-		else

-		{

-			$writer->addAttribute('id',$this->getClientID());

-			$this->getActiveControl()->registerCallbackClientScript(

-				$this->getClientClassName(), $this->getPostBackOptions());

-		}

-		parent::render($writer);

-	}

-

-	/**

-	 * Publish the the rating style css file and rating image files.

-	 */

-	public function onPreRender($param)

-	{

-		parent::onPreRender($param);

-

-		$this->publishRatingListStyle($this->getRatingStyle());

-		$this->_ratingImages = $this->publishRatingListImages($this->getRatingStyle());

-	}

-

-	/**

-	 * Renders the rating images if {@link setReadOnly ReadOnly} is true

-	 * otherwise render the radio buttons.

-	 */

-	public function renderItem($writer,$repeatInfo,$itemType,$index)

-	{

-		if($this->getReadOnly())

-			$this->renderStaticRating($writer, $repeatInfo, $itemType, $index);

-		else

-			parent::renderItem($writer, $repeatInfo, $itemType, $index);

-	}

-

-	/**

-	 * Renders the static rating images.

-	 */

-	protected function renderStaticRating($writer, $repeatInfo, $itemType, $index)

-	{

-		$image = new TImage;

-		$image->setImageUrl($this->_ratingImages[$this->getRatingImageType($index)]);

-		$image->setAlternateText($this->getRating());

-		$image->render($writer);

-	}

-

-	/**

-	 * @param integer rating image index

-	 * @return string the rating image corresponding to current index to be rendered.

-	 */

-	protected function getRatingImageType($index)

+	public function setCaption($value)

 	{

-		$rating = floatval($this->getRating());

-		$int = intval($rating);

-		$limit = $this->getHalfRatingInterval();

-		if($index < $int || ($rating < $index+1 && $rating > $index+$limit[1]))

-			return 'selected';

-		if($rating >= $index+$limit[0] && $rating <= $index+$limit[1])

-			return 'half';

-		return 'blank';

+		parent::setCaption($value);

+		// if it's an active control, this should not be needed. 

+		$this->callClientFunction('setCaption',$value);

 	}

 

 	/**