leaps/leaps-typeahead-widget

This package is abandoned and no longer maintained. No replacement package was suggested.

The bootstrap typeahead widget for the Leaps framework

1.0.2 2016-06-28 03:56 UTC

Requires

• leaps/leaps: >=3.1.4
• leaps/leaps-bootstrap: *

BSD-3-Clause

• Xu Tongle

• widget
• typeahead
• leaps

README

Renders a Twitter Typeahead.js Bootstrap plugin widget.

Installation

The preferred way to install this extension is through composer.

Either run

$ composer require leaps/leaps-typeahead-widget:~1.0

or add

"leaps/leaps-typeahead-widget": "~1.0"

to the require section of your composer.json file.

Usage

Using a model and a remote configuration:

use Leaps\Typeahead\Bloodhound;
use Leaps\Typeahead\TypeAhead;
use Leaps\Helper\Url;

<?php
    $engine = new Bloodhound([
        'name' => 'countriesEngine',
        'clientOptions' => [
            'datumTokenizer' => new \Leaps\Web\JsExpression("Bloodhound.tokenizers.obj.whitespace('name')"),
            'queryTokenizer' => new \Leaps\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 () { console.log(\'event "selected" occured.\'); }'
        ],
        'dataSets' => [
            [
                'name' => 'countries',
                'display' => 'value',
                'source' => $engine->getAdapterScript()
            ]
        ]
    ]
);?>

Note the use of the custom wildcard. It is required as if we use typeahead.js default's wildcard (%QUERY), Leaps 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 Frontend\Controller\Action;

use Leaps\Base\Action;
use Leaps\Helper\Json;
use Leaps\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 = \Leaps::$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' => [
            'className' => 'Frontend\Controller\Action\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.

Testing

$ ./vendor/bin/phpunit

Contributing

Please see CONTRIBUTING for details.

Credits

• Antonio Ramirez
• Alexander Kochetov
• All Contributors

License

The BSD License (BSD). Please see License File for more information.