CAutoComplete

Property Details

autoFill property

public boolean $autoFill;

fill the textinput while still selecting a value, replacing the value if more is typed or something else is selected. Defaults to false.

cacheLength property

public integer $cacheLength;

the number of backend query results to store in cache. If set to 1 (the current result), no caching will happen. Must be >= 1. Defaults to 10.

clientOptions property read-only

protected array getClientOptions()

the javascript options

cssFile property

public mixed $cssFile;

the CSS file used for the widget. Defaults to null, meaning using the default CSS file included together with the widget. If false, no CSS file will be used. Otherwise, the specified CSS file will be included when using this widget.

data property

public array $data;

data that would be saved as client-side data to provide candidate selections. Each array element can be string or an associative array. The url property will be ignored if this property is set.

delay property

public integer $delay;

the delay in milliseconds the autocompleter waits after a keystroke to activate itself. Defaults to 400.

extraParams property

public array $extraParams;

extra parameters for the backend. If you were to specify array('bar'=>4), the autocompleter would call the backend with a GET parameter 'bar' 4. The param can be a function that is called to calculate the param before each request.

formatItem property

public string $formatItem;

a javascript function that provides advanced markup for an item. For each row of results, this function will be called. The returned value will be displayed inside an LI element in the results list. Autocompleter will provide 4 parameters: the results row, the position of the row in the list of results (starting at 1), the number of items in the list of results and the search term. The default behavior assumes that a single row contains a single value.

formatMatch property

public string $formatMatch;

a javascript function that can be used to limit the data that autocomplete searches for matches. For example, there may be items you want displayed to the user, but don't want included in the data that's searched. The function is called with the same arguments as formatItem. Defaults to formatItem.

formatResult property

public string $formatResult;

a javascript function that provides the formatting for the value to be put into the input field. Again three arguments: Data, position (starting with one) and total number of data. The default behavior assumes either plain data to use as result or uses the same value as provided by formatItem.

highlight property

public boolean|string $highlight;

Whether and how to highlight matches in the select box. Set to false to disable. Set to a javascript function to customize. The function gets the value as the first argument and the search term as the second and must return the formatted value. Defaults to Wraps the search term in a <strong> element.

inputClass property

public string $inputClass;

the CSS class for the input element. Defaults to "ac_input".

loadingClass property

public string $loadingClass;

the CSS class used when the data is being loaded from backend. Defaults to "ac_loading".

matchCase property

public boolean $matchCase;

whether or not the comparison is case sensitive. Important only if you use caching. Defaults to false.

matchContains property

public boolean $matchContains;

whether or not the comparison looks inside (i.e. does "ba" match "foo bar") the search results. Important only if you use caching. Don't mix with autofill. Defaults to false.

matchSubset property

public boolean $matchSubset;

whether or not the autocompleter can use a cache for more specific queries. This means that all matches of "foot" are a subset of all matches for "foo". Usually this is true, and using this options decreases server load and increases performance. Only useful with cacheLength settings bigger than one, like 10. Defaults to true.

max property

public integer $max;

limit the number of items in the select box. Is also sent as a "limit" parameter with a remote request. Defaults to 10.

methodChain property

public string $methodChain;

the chain of method calls that would be appended at the end of the autocomplete constructor. For example, ".result(function(...){})" would cause the specified js function to execute when the user selects an option.

minChars property

public integer $minChars;

the minimum number of characters a user has to type before the autocompleter activates. Defaults to 1.

multiple property

public boolean $multiple;

whether to allow more than one autocompleted-value to enter. Defaults to false.

multipleSeparator property

public string $multipleSeparator;

seperator to put between values when using multiple option. Defaults to ", ".

mustMatch property

public boolean $mustMatch;

if set to true, the autocompleter will only allow results that are presented by the backend. Note that illegal values result in an empty input box. Defaults to false.

options property

public array $options;

additional options that can be passed to the constructor of the autocomplete js object. This allows you to override existing functions of the autocomplete js class (e.g. the parse() function)

If you want to provide JavaScript native code, you have to wrap the string with CJavaScriptExpression otherwise it will be enclosed by quotes.

resultsClass property

public string $resultsClass;

the CSS class for the dropdown list. Defaults to "ac_results".

scroll property

public boolean $scroll;

whether to scroll when more results than configured via scrollHeight are available. Defaults to true.

scrollHeight property

public integer $scrollHeight;

height of scrolled autocomplete control in pixels. Defaults to 180.

selectFirst property

public boolean $selectFirst;

if this is set to true, the first autocomplete value will be automatically selected on tab/return, even if it has not been handpicked by keyboard or mouse action. If there is a handpicked (highlighted) result, that result will take precedence. Defaults to true.

textArea property

public boolean $textArea;

whether to show the autocomplete using a text area. Defaults to false, meaning a text field is used.

url property

public string|array $url;

the URL that can return the candidate selections. A 'q' GET parameter will be sent with the URL which contains what the user has entered so far. If the URL is given as an array, it is considered as a route to a controller action and will be used to generate a URL using CController::createUrl; If the URL is an empty string, the currently requested URL is used. This property will be ignored if data is set.

width property

public integer $width;

specify a custom width for the select box. Defaults to the width of the input element.

Method Details

getClientOptions() method

protected array getClientOptions()

protected function getClientOptions()
{
    static $properties=array(
        'minChars', 'delay', 'cacheLength', 'matchSubset',
        'matchCase', 'matchContains', 'mustMatch', 'selectFirst',
        'extraParams', 'multiple', 'multipleSeparator', 'width',
        'autoFill', 'max', 'scroll', 'scrollHeight', 'inputClass',
        'resultsClass', 'loadingClass');
    static $functions=array('formatItem', 'formatMatch', 'formatResult', 'highlight');

    $options=$this->options;
    foreach($properties as $property)
    {
        if($this->$property!==null)
            $options[$property]=$this->$property;
    }
    foreach($functions as $func)
    {
        if($this->$func!==null)
        {
            if($this->$func instanceof CJavaScriptExpression)
                $options[$func]=$this->$func;
            else
                $options[$func]=new CJavaScriptExpression($this->$func);
        }
    }

    return $options;
}

init() method

public void init()

public function init()
{
    list($name,$id)=$this->resolveNameID();
    if(isset($this->htmlOptions['id']))
        $id=$this->htmlOptions['id'];
    else
        $this->htmlOptions['id']=$id;
    if(isset($this->htmlOptions['name']))
        $name=$this->htmlOptions['name'];

    $this->registerClientScript();

    if($this->hasModel())
    {
        $field=$this->textArea ? 'activeTextArea' : 'activeTextField';
        echo CHtml::$field($this->model,$this->attribute,$this->htmlOptions);
    }
    else
    {
        $field=$this->textArea ? 'textArea' : 'textField';
        echo CHtml::$field($name,$this->value,$this->htmlOptions);
    }
}

Initializes the widget. This method registers all needed client scripts and renders the autocomplete input.

registerClientScript() method

public void registerClientScript()

public function registerClientScript()
{
    $id=$this->htmlOptions['id'];

    $acOptions=$this->getClientOptions();
    $options=$acOptions===array()?'{}' : CJavaScript::encode($acOptions);

    $cs=Yii::app()->getClientScript();
    $cs->registerCoreScript('autocomplete');
    if($this->data!==null)
        $data=CJavaScript::encode($this->data);
    else
    {
        $url=CHtml::normalizeUrl($this->url);
        $data='"'.$url.'"';
    }
    $cs->registerScript('Yii.CAutoComplete#'.$id,"jQuery(\"#{$id}\").legacyautocomplete($data,{$options}){$this->methodChain};");

    if($this->cssFile!==false)
        self::registerCssFile($this->cssFile);
}

Registers the needed CSS and JavaScript.

registerCssFile() method

public static void registerCssFile(string $url=NULL)

public static function registerCssFile($url=null)
{
    $cs=Yii::app()->getClientScript();
    if($url===null)
        $url=$cs->getCoreScriptUrl().'/autocomplete/jquery.autocomplete.css';
    $cs->registerCssFile($url);
}

Registers the needed CSS file.