Update TAutoComplete, OnSuggest event for getting suggestions.

1 files changed, 135 insertions, 24 deletions

diff --git a/framework/Web/UI/ActiveControls/TAutoComplete.php b/framework/Web/UI/ActiveControls/TAutoComplete.php
index 601894ff..55ffde04 100644
--- a/framework/Web/UI/ActiveControls/TAutoComplete.php
+++ b/framework/Web/UI/ActiveControls/TAutoComplete.php
@@ -1,77 +1,171 @@
 <?php

-/*

- * Created on 7/05/2006

+/**

+ * TAutoComplete class file.

+ *

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

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

+ * @copyright Copyright &copy; 2006 PradoSoft

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

+ * @version $Revision: $  : $

+ * @package System.Web.UI.ActiveControls

  */

 

+/**

+ * TAutoComplete class.

+ * 

+ * TAutoComplete is a textbox that provides a list of suggestion on 

+ * the current partial word typed in the textbox. The suggestions are

+ * requested using callbacks, and raises the {@link onSuggestion OnSuggestion}

+ * event. The events of the TActiveText (from which TAutoComplete is extended from)

+ * and {@link onSuggestion OnSuggestion} are mutually exculsive. That is,

+ * if {@link onTextChange OnTextChange} and/or {@link onCallback OnCallback}

+ * events are raise, then {@link onSuggestion OnSuggestion} will not be raise, and

+ * vice versa. 

+ * 

+ * The list of suggestions should be set in the {@link onSuggestion OnSuggestion}

+ * event handler. The partial word to match the suggestion is in the 

+ * {@link TCallbackEventParameter::getParameter TCallbackEventParameter::Parameter}

+ * property. The datasource of the TAutoComplete must be set using {@link setDataSource}

+ * method. This sets the datasource for the suggestions repeater, available through

+ * the {@link getSuggestions Suggestions} property. Header, footer templates and 

+ * other properties of the repeater can be access via the {@link getSuggestions Suggestions}

+ * property (e.g. they can be set in the .page templates).

+ * 

+ * To return the list of suggestions back to the browser, in your {@link onSuggestion OnSuggestion}

+ * event handler, do

+ * <code>

+ * function autocomplete_suggestion($sender, $param)

+ * {

+ *   $token = $param->getParameter(); //the partial word to match

+ *   $sender->setDataSource($this->getSuggestionsFor($token)); //set suggestions

+ *   $sender->dataBind();

+ *   $sender->flush($param->getOutput()); //sends suggestion back to browser.

+ * }

+ * </code>

+ * 

+ * TAutoComplete allows multiple suggestions within one textbox with each

+ * word or phrase separated by any characters specified in the 

+ * {@link setSeparator Separator} property. The {@link setFrequency Frequency}

+ * and {@link setMinChars MinChars} properties sets the delay and minimum number

+ * of characters typed, respectively, before requesting for sugggestions.

+ * 

+ * Use {@link onTextChange OnTextChange} and/or {@link onCallback OnCallback} events

+ * to handle post backs due to {@link setAutoPostBack AutoPostBack}.

+ * 

+ * In the {@link getSuggestions Suggestions} TRepater item template, all HTML text elements

+ * are considered as text for the suggestion. Text within HTML elements with CSS class name

+ * "informal" are ignored as text for suggestions.

+ *

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

+ * @version $Revision: $  Mon Jun 19 03:50:05 EST 2006 $

+ * @package System

+ * @since 3.0

+ */

 class TAutoComplete extends TActiveTextBox implements INamingContainer

 {

 	/**

 	 * @var ITemplate template for repeater items

 	 */

 	private $_repeater=null;

+	/**

+	 * @var TPanel result panel holding the suggestion items.

+	 */

 	private $_resultPanel=null;

 	

+	/**

+	 * @return string word or token separators (delimiters).

+	 */

 	public function getSeparator()

 	{

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

 	}

 	

+	/**

+	 * @return string word or token separators (delimiters).

+	 */

 	public function setSeparator($value)

 	{

 		$this->setViewState('tokens', TPropertyValue::ensureString($value), '');

 	}

 	

+	/**

+	 * @return float maximum delay (in seconds) before requesting a suggestion.

+	 */

 	public function getFrequency()

 	{

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

 	}

 	

+	/**

+	 * @param float maximum delay (in seconds) before requesting a suggestion.

+	 * Default is 0.4.

+	 */

 	public function setFrequency($value)

 	{

 		$this->setViewState('frequency', TPropertyValue::ensureFloat($value),'');

 	}

 	

+	/**

+	 * @return integer minimum number of characters before requesting a suggestion.

+	 */

 	public function getMinChars()

 	{

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

 	}

 	

+	/**

+	 * @param integer minimum number of characters before requesting a suggestion.

+	 */

 	public function setMinChars($value)

 	{

 		$this->setViewState('minChars', TPropertyValue::ensureInteger($value), '');

 	}

 	

 	/**

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

-	 * ICallbackEventHandler} interface. If {@link getCausesValidation

-	 * CausesValidation} is true, it will invoke the page's {@link TPage::

-	 * validate validate} method first. It will raise {@link onCallback

-	 * OnCallback} event and then the {@link onClick OnClick} event. This method

-	 * is mainly used by framework and control developers.

+	 * Raises the callback event. This method is overrides the parent implementation.

+	 * If {@link setAutoPostBack AutoPostBack} is enabled it will raise 

+	 * {@link onTextChanged OnTextChanged} event event and then the 

+	 * {@link onCallback OnCallback} event. The {@link onSuggest OnSuggest} event is

+	 * raise if the request is to find sugggestions, the {@link onTextChanged OnTextChanged}

+	 * and {@link onCallback OnCallback} events are <b>NOT</b> raised.

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

 	 * @param TCallbackEventParameter the event parameter

 	 */	

  	public function raiseCallbackEvent($param)

 	{

-		$this->onCallback($param);

+		$token = $param->getParameter();

+		if(is_array($token) && count($token) == 2 && $token[1] === '__TAutComplete_onSuggest__')

+		{

+			$parameter = new TCallbackEventParameter($this->getResponse(), $token[0]);

+			$this->onSuggest($parameter);

+		}

+		else if($this->getAutoPostBack())

+			parent::raiseCallbackEvent($param);

 	}

 

 	/**

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

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

+	 * This method is invoked when a autocomplete suggestion is requested. 

+	 * The method raises 'OnSuggest' event. 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 onCallback($param)

+	public function onSuggest($param)

 	{

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

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

 	}

-		

+	

+	/**

+	 * @param array data source for suggestions.

+	 */

 	public function setDataSource($data)

 	{

 		$this->getSuggestions()->setDataSource($data);

 	}

 	

+	/**

+	 * @return TPanel suggestion results panel.

+	 */

 	public function getResultPanel()

 	{

 		if(is_null($this->_resultPanel))

@@ -79,6 +173,9 @@ class TAutoComplete extends TActiveTextBox implements INamingContainer
 		return $this->_resultPanel;

 	}

 	

+	/**

+	 * @return TPanel new instance of result panel. Default uses TPanel.

+	 */

 	protected function createResultPanel()

 	{

 		$panel = Prado::createComponent('System.Web.UI.WebControls.TPanel');

@@ -98,7 +195,7 @@ class TAutoComplete extends TActiveTextBox implements INamingContainer
 	}

 	

 	/**

-	 * 

+	 * @return TRepeater new instance of TRepater to render the list of suggestions.

 	 */

 	protected function createRepeater()

 	{

@@ -110,6 +207,9 @@ class TAutoComplete extends TActiveTextBox implements INamingContainer
 		return $repeater;

 	}

 

+	/**

+	 * Renders the end tag and registers javascript effects library.

+	 */

 	public function renderEndTag($writer)

 	{

 		$this->getPage()->getClientScript()->registerPradoScript('effects');

@@ -117,22 +217,29 @@ class TAutoComplete extends TActiveTextBox implements INamingContainer
 		$this->renderResultPanel($writer);

 	}

 	

-	public function renderResultPanel($writer)

+	/**

+	 * Renders the result panel.

+	 * @param THtmlWriter the renderer.

+	 */

+	protected function renderResultPanel($writer)

 	{

 		$this->getResultPanel()->render($writer);	

 	}

 	

-	public function render($writer)

+	/**

+	 * Flush and returns the suggestions content back to the browser client.

+	 * @param THtmlWriter the renderer.

+	 */

+	public function flush($writer)

 	{

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

-		{

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

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

 				$this->renderSuggestions($writer);

-		}

-		else

-			parent::render($writer);	

 	}

 

+	/**

+	 * Renders the suggestions repeater.

+	 * @param THtmlWriter the renderer.

+	 */

 	protected function renderSuggestions($writer)

 	{

 		if($this->getSuggestions()->getItems()->getCount() > 0)

@@ -151,11 +258,15 @@ class TAutoComplete extends TActiveTextBox implements INamingContainer
 		$this->getActiveControl()->getClientSide()->setEnablePageStateUpdate(false);

 		if(strlen($string = $this->getSeparator()))

 		{

+			$string = strtr($string,array('\t'=>"\t",'\n'=>"\n",'\r'=>"\r"));

 			$token = preg_split('//', $string, -1, PREG_SPLIT_NO_EMPTY);

 			$options['tokens'] = TJavascript::encode($token,false);

 		} 

 		if($this->getAutoPostBack())

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

+		{

+			$options = array_merge($options,$this->getPostBackOptions());

+			$options['AutoPostBack'] = true;

+		}

 		$options['ResultPanel'] = $this->getResultPanel()->getClientID();

 		$options['ID'] = $this->getClientID();

 		$options['EventTarget'] = $this->getUniqueID();