From 3a30ede1c03fdd097398b14734822f7ce8e46b6b Mon Sep 17 00:00:00 2001 From: wei <> Date: Sat, 17 Jun 2006 10:28:26 +0000 Subject: Update TAutoComplete, OnSuggest event for getting suggestions. --- framework/Web/UI/ActiveControls/TAutoComplete.php | 159 ++++++++++++++++++---- 1 file changed, 135 insertions(+), 24 deletions(-) (limited to 'framework/Web/UI/ActiveControls/TAutoComplete.php') 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 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 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 + * + * 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. + * } + * + * + * 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 + * @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 NOT 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(); -- cgit v1.2.3