yii2-extension yii2-type-ahead-widget {🖫 39,123, ⚐ 5, ★ 24}

2amigos/yii2-type-ahead-widget

The bootstrap typeahead widget for the Yii framework

Friday, May 15, 2015
by tonydspaniard
Repository
21 Watchers
24 Stars
39,123 Installations

PHP
1 Dependents
0 Suggesters
7 Forks
3 Open issues
5 Versions
9 % Grown

The README.md

, _(*1)

Renders a Twitter Typeahead.js Bootstrap plugin widget., _(*2)

Installation

The preferred way to install this extension is through composer., _(*3)

Either run, _(*4)

$ composer require 2amigos/yii2-type-ahead-widget:~2.0

or add, _(*5)

"2amigos/yii2-type-ahead-widget": "~2.0"

to the require section of your composer.json file., _(*6)

Usage

Using a model and a remote configuration:, _(*7)

use dosamigos\typeahead\Bloodhound;
use dosamigos\typeahead\TypeAhead;
use yii\helpers\Url;

 'countriesEngine',
        'clientOptions' => [
            'datumTokenizer' => new \yii\web\JsExpression("Bloodhound.tokenizers.obj.whitespace('name')"),
            'queryTokenizer' => new \yii\web\JsExpression("Bloodhound.tokenizers.whitespace"),
            'remote' => [
                'url' => Url::to(['country/autocomplete', 'query'=>'QRY']),
                'wildcard' => 'QRY'
            ]
        ]
    ]);
?>
= $form->field($model, 'country')->widget(
    TypeAhead::className(),
    [
        'options' => ['class' => 'form-control'],
        'engines' => [ $engine ],
        'clientOptions' => [
            'highlight' => true,
            'minLength' => 3
        ],
        'clientEvents' => [
            'typeahead:selected' => 'function (e, o) { console.log("event \'selected\' occured on " + o.value + "."); }'
        ],
        'dataSets' => [
            [
                'name' => 'countries',
                'displayKey' => 'value',
                'source' => $engine->getAdapterScript()
            ]
        ]
    ]
);?>

Note the use of the custom wildcard. It is required as if we use typeahead.js default's wildcard (%QUERY), Yii2 will automatically URL encode it thus making the wrong configuration for token replacement., _(*8)

The results need to be JSON encoded as specified on the plugin documentation. The following is an example of a custom Action class that you could plug to any Controller:, _(*9)

namespace frontend\controllers\actions;

use yii\base\Action;
use yii\helpers\Json;
use yii\base\InvalidConfigException;

class AutocompleteAction extends Action
{
    public $tableName;

    public $field;

    public $clientIdGetParamName = 'query';

    public $searchPrefix = '';

    public $searchSuffix = '%';

    public function init()
    {
        if($this->tableName === null) {
            throw new  InvalidConfigException(get_class($this) . '::$tableName must be defined.');
        }
        if($this->field === null) {
            throw new  InvalidConfigException(get_class($this) . '::$field must be defined.');
        }
        parent::init();
    }

    public function run()
    {
        $value = $this->searchPrefix . $_GET[$this->clientIdGetParamName] . $this->searchSuffix;
        $rows = \Yii::$app->db
            ->createCommand("SELECT {$this->field} AS value FROM {$this->tableName} WHERE {$this->field} LIKE :field ORDER BY {$this->field}")
            ->bindValues([':field' => $value])
            ->queryAll();

        echo Json::encode($rows);
    }
}

And how to configure it on your Controller class:, _(*10)

public function actions()
{
    return [
        'autocomplete' => [
            'class' => 'frontend\controllers\actions\AutocompleteAction',
            'tableName' => Country::tableName(),
            'field' => 'name'
        ]
    ];
}

Theming

Twitter Typeahead.js Bootstrap plugin does not style the dropdown nor the hint or the input-field. It does it this way in order for you to customize it so it suits your application., _(*11)

We have included a stylesheet with hints to match form-control bootstrap classes and other tweaks so you can easily identify the classes and style it., _(*12)