This is a Symfony Bundle that provides an autocomplete Form Type. This was designed for Symfony v4+. Currently, this widget uses Select2 as its base. In the future I might add other 'autocomplete' widgets using different interfaces.
This is a replacement for my older Typeahead Bundle that was originally for Symfony v2 and hasn't been updated in years (but has served me well!). This is not a one-for-one replacement, but rather a more modern approach to doing things.
I'm still working on features and ironing out some small issues. I have not tagged any releases yet.
- Supports Entity and Non-Entity lookups using a single class type.
- Supports AJAX or Array lists.
- Easily add the javascript code to your existing bundler (webpack, etc), or use it directly via a
<script>
tag. - Support different themes like
bootstrap
. - Supports
tagging
- The ability of adding new entities or items. - Form types for
Select
andVue-Multiselect
widgets. Vue-Multiselect type is not documented yet.
-
This bundle requires the Select2 or Vue-multiselect javascript and CSS code, but does not provide it directly. You must include it yourself, eg:
yarn add select2
, and add it to your webpack or other bundler configuration. -
Select2
requires jQuery and is not actually provided in this bundle. You must provide it yourself, eg:yarn add jquery
Note: The examples below use the bootstrap
theme from the NPM package select2-bootstrap-theme
(yarn add select2-bootstrap-theme
).
A simple select box that allows a single entity User
to be selected from an AJAX request.
use Lifo\AutocompleteBundle\Form\Type\Select2Type;
$builder->add('user', Select2Type::class, [
'route' => 'users_lookup',
//'url' => '/absolute/url/instead/of/route',
'min_input_length' => 1,
'placeholder' => 'Search for user ...',
]);
A simple select box that allows a multiple User
entities to be selected from an AJAX request.
$builder->add('users', Select2Type::class, [
'route' => 'users_lookup',
'min_input_length' => 1,
'multiple' => true,
'placeholder' => 'Search for user ...',
]);
A simple select box that uses a plain array of choices.
$builder->add('status', Select2Type::class, [
'help_block' => 'Inactive users cannot login.',
'choices' => [
'Active' => 1,
'Inactive' => 0,
],
]);
There are a lot of options to customize the way the autocomplete widget functions. Defaults are shown.
Note: A route
, url
, or choices
must be specified for the widget to function.
Option | Default | Description |
---|---|---|
route | null |
Symfony route name to generate an URL to perform an AJAX search request. |
route_params | null |
Parameter array to generate the route |
url | null |
An absolute URL to perform the AJAX search request from instead of a route name. |
choices | null |
An keyed array of choices to populate the select box with instead of using AJAX. |
class | null |
The Entity class representing the items in the results. Can be null to use non-entities. |
property | "id" |
The unique ID property name to use for the id of each item. |
text_property | null |
The property to render the selection text from. Can be null if your Entity has a __toString method. |
multiple | false |
If true, multiple items can be selected. |
min_input_length | 0 |
Minimum input length required before a search request is performed. |
max_selections | 0 |
Maximum selections allowed (multiple is true). Set to 0 for no limit. |
delay | 250 |
Delay, in milliseconds before a search request is performed. |
tags | false |
Enable tagging support (adding new entries). |
placeholder | null |
Placeholder text shown in the widget when nothing is selected. |
allow_clear | true |
Allow the selection(s) to be cleared with a single click of an "x" icon. |
close_on_select | true |
Close the dropdown after a selection is made. |
theme | "bootstrap" |
Theme to use. 'default' is the standard option for Select2. |
language | "en" |
Lanuage to use. |
dropdown_auto_width | false |
If true, the dropdown width will expand to its contents. |
dropdown_parent | null |
CSS Selector target for the dropdown parent placement. Useful if you need to target a modal, etc. |
dir | "ltr" |
Language direction: Left-to-Right (rtl), or Right-to-Left (ltr) |
disabled | false |
If true, the select will be disabled. |
transformer | null |
Custom DataTransformer to use. |
composer require lifo/autocomplete-bundle
If you're using Flex then the bundle will work w/o any other configuration.
If you're not using Flex
then you'll need to register the bundle in bundles.php
:
// config/bundles.php
return [
// ...
Lifo\AutocompleteBundle\LifoAutocompleteBundle::class => ['all' => true],
// ...
];
By default, the form theme is enabled automatically in Twig, but you can disable this if you need to with the following config:
lifo_autocomplete:
autoconfigure: false
If autoconfigure
is disabled, you'll have to manually update your Twig config:
# config/packages/twig.yaml
form_themes:
- '@LifoAutocomplete/autocomplete.html.twig'
Symfony v3 is not officially supported, but might work if you manually register the
bundle in app/AppKernel.php
$bundles = array(
// ...
new Lifo\AutocompleteBundle\LifoAutocompleteBundle(),
);
This is an example of how to add the javascript and CSS to your app. The concept here is similar to other bundlers as well.
In your main entry point you would add something similar as this:
// assets/app.js
import 'bootstrap'
import 'select2'
require('select2/dist/css/select2.min.css');
// ...
You can include the required javascript by using straight script tags too. The paths here assume the files
are already in your public
web directory.
<script src="js/select2/dist/js/select2.js"></script>
<link href="css/select2.min.css" type="text/css" rel="stylesheet" />
AJAX responses and the simple Array lists require the following format:
[
'results' => [
[
'id' => 'unique ID',
'text' => 'text displayed',
],
[
'id' => 'unique ID',
'text' => 'text displayed',
],
],
'more' => true|false,
// or:
// 'pagination' => [
// 'more' => true|false
// ]
Select2
sends the following on AJAX requests.
term
- The current search term in the search box.q
- Contains the same contents asterm
._type
- "request type". Will usually be query, but changes to query_append for paginated requests.page
- The current page number to request. Only sent for paginated (infinite scrolling) searches.