TypeAhead Widget

What is Bootstrap TypeAhead Widget?

It allows you to make use of the Twitter Typeahead.js Bootstrap plugin in your forms.

Installation

The preferred way to install this extension is through composer.

Either run

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

or add the following to the require section of your application's composer.json file:

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

Usage example

Using a model and a remote configuration:

<?php 
use dosamigos\typeahead\Bloodhound;
use dosamigos\typeahead\TypeAhead;
use yii\helpers\Url;
use yii\web\JsExpression;
?>
<?php
    $engine = new Bloodhound([
        'name' => 'countriesEngine',
        'clientOptions' => [
            'datumTokenizer' => new JsExpression("Bloodhound.tokenizers.obj.whitespace('name')"),
            'queryTokenizer' => new 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
        ],
        '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.

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:


namespace app\controllers\actions;


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

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:

public function actions()
{
	return [
		'autocomplete' => [
			'class' => 'app\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.

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.

Share this

Contributors Thanks All

 

Do you have a good idea? Why Don't We Talk?