## Class TAutoComplete

Description

Implements interfaces:

- INamingContainer

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 onSuggestion event. The events of the TActiveText (from which TAutoComplete is extended from) and onSuggestion are mutually exculsive. That is, if onTextChange and/or OnCallback events are raise, then onSuggestion will not be raise, and vice versa.

The list of suggestions should be set in the onSuggestion event handler. The partial word to match the suggestion is in the TCallbackEventParameter::getCallbackParameter property. The datasource of the TAutoComplete must be set using setDataSource method. This sets the datasource for the suggestions repeater, available through the Suggestions property. Header, footer templates and other properties of the repeater can be access via the Suggestions property and its sub-properties.

The TextCssClass property if set is used to find the element within the Suggestions.ItemTemplate and Suggestions.AlternatingItemTemplate that contains the actual text for the suggestion selected. That is, only text inside elements with CSS class name equal to TextCssClass will be used as suggestions.

To return the list of suggestions back to the browser, supply a non-empty data source and call databind. For example,

     function autocomplete_suggestion($sender, $param)
     {
       $token = $param->getToken(); //the partial word to match
       $sender->setDataSource($this->getSuggestionsFor($token)); //set suggestions
       $sender->dataBind();
     }

The suggestion will be rendered when the dataBind() method is called <strong>during a callback request</strong>.

When an suggestion is selected, that is, when the use has clicked, pressed the "Enter" key, or pressed the "Tab" key, the OnSuggestionSelected event is raised. The TCallbackEventParameter::getCallbackParameter property contains the index of the selected suggestion.

TAutoComplete allows multiple suggestions within one textbox with each word or phrase separated by any characters specified in the Separator property. The Frequency and MinChars properties sets the delay and minimum number of characters typed, respectively, before requesting for sugggestions.

Use onTextChange and/or OnCallback events to handle post backs due to AutoPostBack.

In the 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.

- since: 3.1
- version: $Id: TAutoComplete.php 2315 2007-10-11 12:04:08Z tof $
- author: Wei Zhuo <weizhuo[at]gmail[dot]com>

Located in /Web/UI/ActiveControls/TAutoComplete.php (line 84)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TWebControl
                |
                --TTextBox
                   |
                   --TActiveTextBox
                      |
                      --TAutoComplete

Method Summary
TRepeater createRepeater ()
TPanel createResultPanel ()
void dataBind ()
string getClientClassName ()
float getFrequency ()
integer getMinChars ()
array getPostBackOptions ()
TPanel getResultPanel ()
string getSeparator ()
TRepeater getSuggestions ()
string getTextCssClass ()
void onSuggest (TCallbackEventParameter $param)
void onSuggestionSelected (TCallbackEventParameter $param)
void raiseCallbackEvent (TCallbackEventParameter $param)
void renderCallback (THtmlWriter $writer)
void renderClientControlScript (mixed $writer)
void renderEndTag (mixed $writer)
void renderResultPanel (THtmlWriter $writer)
void renderSuggestions (THtmlWriter $writer)
void setDataSource (array $data)
void setFrequency (float $value)
void setMinChars (integer $value)
string setSeparator (mixed $value)
void setTextCssClass (string $value)
Methods
createRepeater (line 267)

- return: new instance of TRepater to render the list of suggestions.
- access: protected

TRepeater createRepeater ()
createResultPanel (line 246)

- return: new instance of result panel. Default uses TPanel.
- access: protected

TPanel createResultPanel ()
dataBind (line 226)

Overrides parent implementation. Callback renderSuggestions() when page's IsCallback property is true.

- access: public

void dataBind ()

Redefinition of:

TControl::dataBind()
  Performs the databinding for this control.

getClientClassName (line 363)

- return: corresponding javascript class name for this TActiveButton.
- access: protected

string getClientClassName ()

Redefinition of:

TActiveTextBox::getClientClassName()
  Gets the name of the javascript class responsible for performing postback for this control.

getFrequency (line 114)

- return: maximum delay (in seconds) before requesting a suggestion.
- access: public

float getFrequency ()
getMinChars (line 131)

- return: minimum number of characters before requesting a suggestion.
- access: public

integer getMinChars ()
getPostBackOptions (line 322)

- return: list of callback options.
- access: protected

array getPostBackOptions ()

Redefinition of:

TTextBox::getPostBackOptions()
  Gets the post back options for this textbox.

getResultPanel (line 236)

- return: suggestion results panel.
- access: public

TPanel getResultPanel ()
getSeparator (line 98)

- return: word or token separators (delimiters).
- access: public

string getSeparator ()
getSuggestions (line 257)

- return: suggestion list repeater
- access: public

TRepeater getSuggestions ()
getTextCssClass (line 155)

- return: Css class name of the element to use for suggestion.
- access: public

string getTextCssClass ()
onSuggest (line 197)

This method is invoked when an 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.

- access: public

void onSuggest (TCallbackEventParameter $param)

- TCallbackEventParameter $param: event parameter to be passed to the event handlers

onSuggestionSelected (line 209)

This method is invoked when an autocomplete suggestion is selected.

The method raises 'OnSuggestionSelected' event. If you override this method, be sure to call the parent implementation so that the event handler can be invoked.

- access: public

void onSuggestionSelected (TCallbackEventParameter $param)

- TCallbackEventParameter $param: event parameter to be passed to the event handlers

raiseCallbackEvent (line 170)

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

If AutoPostBack is enabled it will raise OnTextChanged event event and then the OnCallback event. The OnSuggest event is raise if the request is to find sugggestions, the OnTextChanged and OnCallback events are NOT raised. This method is mainly used by framework and control developers.

- access: public

void raiseCallbackEvent (TCallbackEventParameter $param)

- TCallbackEventParameter $param: the event parameter

Redefinition of:

TActiveTextBox::raiseCallbackEvent()
  Raises the callback event. This method is required by ICallbackEventHandler interface.

renderCallback (line 300)

Renders the suggestions during a callback respones.

- access: public

void renderCallback (THtmlWriter $writer)

- THtmlWriter $writer: the renderer.

renderClientControlScript (line 356)

Override parent implementation, no javascript is rendered here instead the javascript required for active control is registered in addAttributesToRender.

- access: protected

void renderClientControlScript (mixed $writer)

Redefinition of:

TActiveTextBox::renderClientControlScript()
  Override parent implementation, no javascript is rendered here instead the javascript required for active control is registered in addAttributesToRender.

renderEndTag (line 280)

Renders the end tag and registers javascript effects library.

- access: public

void renderEndTag (mixed $writer)

Redefinition of:

TWebControl::renderEndTag()
  Renders the closing tag for the control

renderResultPanel (line 291)

Renders the result panel.

- access: protected

void renderResultPanel (THtmlWriter $writer)

- THtmlWriter $writer: the renderer.

renderSuggestions (line 309)

Renders the suggestions repeater.

- access: public

void renderSuggestions (THtmlWriter $writer)

- THtmlWriter $writer: the renderer.

setDataSource (line 217)

- access: public

void setDataSource (array $data)

- array $data: data source for suggestions.

setFrequency (line 123)

- access: public

void setFrequency (float $value)

- float $value: maximum delay (in seconds) before requesting a suggestion. Default is 0.4.

setMinChars (line 139)

- access: public

void setMinChars (integer $value)

- integer $value: minimum number of characters before requesting a suggestion.

setSeparator (line 106)

- return: word or token separators (delimiters).
- access: public

string setSeparator (mixed $value)
setTextCssClass (line 147)

- access: public

void setTextCssClass (string $value)

- string $value: Css class name of the element to use for suggestion.

#### Inherited Methods

Inherited From TActiveTextBox

> TActiveTextBox::__construct()
> TActiveTextBox::addAttributesToRender()
> TActiveTextBox::getActiveControl()
> TActiveTextBox::getClientClassName()
> TActiveTextBox::getClientSide()
> TActiveTextBox::onCallback()
> TActiveTextBox::raiseCallbackEvent()
> TActiveTextBox::renderClientControlScript()
> TActiveTextBox::setText()

Inherited From TTextBox

> TTextBox::addAttributesToRender()
> TTextBox::getAutoCompleteType()
> TTextBox::getAutoPostBack()
> TTextBox::getAutoTrim()
> TTextBox::getCausesValidation()
> TTextBox::getClientClassName()
> TTextBox::getColumns()
> TTextBox::getData()
> TTextBox::getDataChanged()
> TTextBox::getEnableClientScript()
> TTextBox::getMaxLength()
> TTextBox::getPersistPassword()
> TTextBox::getPostBackOptions()
> TTextBox::getReadOnly()
> TTextBox::getRows()
> TTextBox::getSafeText()
> TTextBox::getSafeTextParser()
> TTextBox::getTagName()
> TTextBox::getText()
> TTextBox::getTextMode()
> TTextBox::getValidationGroup()
> TTextBox::getValidationPropertyValue()
> TTextBox::getWrap()
> TTextBox::loadPostData()
> TTextBox::onTextChanged()
> TTextBox::raisePostDataChangedEvent()
> TTextBox::renderClientControlScript()
> TTextBox::renderContents()
> TTextBox::setAutoCompleteType()
> TTextBox::setAutoPostBack()
> TTextBox::setAutoTrim()
> TTextBox::setCausesValidation()
> TTextBox::setColumns()
> TTextBox::setData()
> TTextBox::setEnableClientScript()
> TTextBox::setMaxLength()
> TTextBox::setPersistPassword()
> TTextBox::setReadOnly()
> TTextBox::setRows()
> TTextBox::setText()
> TTextBox::setTextMode()
> TTextBox::setValidationGroup()
> TTextBox::setWrap()

Inherited From TWebControl

> TWebControl::addAttributesToRender()
> TWebControl::clearStyle()
> TWebControl::copyBaseAttributes()
> TWebControl::createStyle()
> TWebControl::getAccessKey()
> TWebControl::getBackColor()
> TWebControl::getBorderColor()
> TWebControl::getBorderStyle()
> TWebControl::getBorderWidth()
> TWebControl::getCssClass()
> TWebControl::getDisplay()
> TWebControl::getFont()
> TWebControl::getForeColor()
> TWebControl::getHasStyle()
> TWebControl::getHeight()
> TWebControl::getStyle()
> TWebControl::getTabIndex()
> TWebControl::getTagName()
> TWebControl::getToolTip()
> TWebControl::getWidth()
> TWebControl::render()
> TWebControl::renderBeginTag()
> TWebControl::renderContents()
> TWebControl::renderEndTag()
> TWebControl::setAccessKey()
> TWebControl::setBackColor()
> TWebControl::setBorderColor()
> TWebControl::setBorderStyle()
> TWebControl::setBorderWidth()
> TWebControl::setCssClass()
> TWebControl::setDisplay()
> TWebControl::setForeColor()
> TWebControl::setHeight()
> TWebControl::setStyle()
> TWebControl::setTabIndex()
> TWebControl::setToolTip()
> TWebControl::setWidth()

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::addToPostDataLoader()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::convertUniqueIdToClientId()
> TControl::createChildControls()
> TControl::createControlCollection()
> TControl::dataBind()
> TControl::dataBindChildren()
> TControl::dataBindProperties()
> TControl::ensureChildControls()
> TControl::findControl()
> TControl::findControlsByID()
> TControl::findControlsByType()
> TControl::focus()
> TControl::getAdapter()
> TControl::getAllowChildControls()
> TControl::getAttribute()
> TControl::getAttributes()
> TControl::getChildControlsCreated()
> TControl::getClientID()
> TControl::getControls()
> TControl::getControlStage()
> TControl::getControlState()
> TControl::getCustomData()
> TControl::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasChildInitialized()
> TControl::getHasControls()
> TControl::getHasInitialized()
> TControl::getHasLoaded()
> TControl::getHasLoadedPostData()
> TControl::getHasPreRendered()
> TControl::getID()
> TControl::getNamingContainer()
> TControl::getPage()
> TControl::getParent()
> TControl::getRegisteredObject()
> TControl::getSkinID()
> TControl::getSourceTemplateControl()
> TControl::getTemplateControl()
> TControl::getUniqueID()
> TControl::getViewState()
> TControl::getVisible()
> TControl::hasAttribute()
> TControl::initRecursive()
> TControl::isDescendentOf()
> TControl::isObjectRegistered()
> TControl::loadRecursive()
> TControl::loadState()
> TControl::loadStateRecursive()
> TControl::onDataBinding()
> TControl::onInit()
> TControl::onLoad()
> TControl::onPreRender()
> TControl::onUnload()
> TControl::preRenderRecursive()
> TControl::raiseBubbleEvent()
> TControl::registerObject()
> TControl::removeAttribute()
> TControl::removedControl()
> TControl::render()
> TControl::renderChildren()
> TControl::renderControl()
> TControl::saveState()
> TControl::saveStateRecursive()
> TControl::setAdapter()
> TControl::setAttribute()
> TControl::setChildControlsCreated()
> TControl::setControlStage()
> TControl::setControlState()
> TControl::setCustomData()
> TControl::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> TControl::trackViewState()
> TControl::traverseChildControls()
> TControl::unbindProperty()
> TControl::unloadRecursive()
> TControl::unregisterObject()
> TControl::__get()

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants

#### Inherited Constants

Inherited from TTextBox

> TTextBox::DEFAULT_COLUMNS
> TTextBox::DEFAULT_ROWS

Inherited from TControl

> TControl::AUTOMATIC_ID_PREFIX
> TControl::CLIENT_ID_SEPARATOR
> TControl::CS_CHILD_INITIALIZED
> TControl::CS_CONSTRUCTED
> TControl::CS_INITIALIZED
> TControl::CS_LOADED
> TControl::CS_PRERENDERED
> TControl::CS_STATE_LOADED
> TControl::ID_FORMAT
> TControl::ID_SEPARATOR
> TControl::IS_CHILD_CREATED
> TControl::IS_CREATING_CHILD
> TControl::IS_DISABLE_THEMING
> TControl::IS_DISABLE_VIEWSTATE
> TControl::IS_ID_SET
> TControl::IS_SKIN_APPLIED
> TControl::IS_STYLESHEET_APPLIED
> TControl::RF_ADAPTER
> TControl::RF_AUTO_BINDINGS
> TControl::RF_CHILD_STATE
> TControl::RF_CONTROLS
> TControl::RF_CONTROLSTATE
> TControl::RF_DATA_BINDINGS
> TControl::RF_EVENTS
> TControl::RF_NAMED_CONTROLS
> TControl::RF_NAMED_CONTROLS_ID
> TControl::RF_NAMED_OBJECTS
> TControl::RF_SKIN_ID

Documentation generated on Mon, 21 Apr 2008 11:30:44 -0400 by phpDocumentor 1.3.0RC4