atk4/ui

:::{php:namespace} Atk4\Ui
:::

(autocomplete)=

# AutoComplete Form Control

:::{php:class} Form\Control\AutoComplete
:::

Agile UI uses "Form\Control\Dropdown" by default on the form, but there is also implementation
for AutoComplete form control. Although they look similar, there are some differences:

- AutoComplete will perform callback to fetch values.
- AutoComplete can use callback to format options (both keys and values).
- AutoComplete can search in multiple fields.
- AutoComplete can use form current (dirty) values to apply dependency and limit options.
- AutoComplete can have multiple selection.
- AutoComplete has additional feature called "Plus"
- AutoComplete only works with models. Won't work for pre-defined value lists.

AutoComplete can be a drop-in replacement for Dropdown.

## Using Plus mode

In your application, it is handy if you can automatically add a missing "client" from the form
where you add an invoice. AutoComplete implements "Plus" mode which will automatically open a modal
form where you can enter new record details.

The form save will re-use the model of your auto-complete, so be sure to set() defaults and
addCondition()s:

```
$form->addControl('test', [\Atk4\Ui\Form\Control\AutoComplete::class, 'plus' => true])
    ->setModel(new Country($db));
```

## Specifying in Model

You can also specify that you prefer to use AutoComplete inside your model definition:

```
$model->hasOne('country_id', ['model' => [Country::class], 'ui' => ['form' => [\Atk4\Ui\Form\Control\AutoComplete::class]]]);
```

## Advanced Usage

You can do much more with AutoComplete form control by passing dropdown settings:

```
$form->addControl('test', [
    \Atk4\Ui\Form\Control\AutoComplete::class,
    'settings' => [
        'allowReselection' => true,
        'selectOnKeydown' => false,
        'onChange' => new \Atk4\Ui\Js\JsExpression('function (value, t, c) {
            if ($(this).data(\'value\') !== value) {
                $(this).parents(\'.form\').form(\'submit\');
                $(this).data(\'value\', value);
            }}'),
    ],
])->setModel(new Country($db));
```

## Lookup Form Control

In 1.6 we have introduced Lookup form control, which is identical to AutoComplete but additionally allows
use of Filters:

```
$form = \Atk4\Ui\Form::addTo($app, ['class.segment' => true]);
\Atk4\Ui\Label::addTo($form, ['Add city', 'class.top attached' => true], ['AboveControls']);

$l = $form->addControl('city', [\Atk4\Ui\Form\Control\Lookup::class]);

// will restraint possible city value in droddown base on country and/or language
$l->addFilter('country', 'Country');
$l->addFilter('language', 'Lang');

// make sure country and language belong to your model
$l->setModel(new City($db));
```

Possibly this feature will be introduced into "AutoComplete" class.