Introduction

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.

Features

• 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.

Requirements

• This bundle requires the Select2 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

Examples

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,
    ],
]);

Configuration

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.

Installation

Symfony v4+

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],
    // ...
];

Twig Configuration

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.x

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(),
);

Webpack

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');
// ...

Script Tag

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" />

Data Format

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
  // ]

AJAX Requests

Select2 sends the following on AJAX requests.

• term - The current search term in the search box.
• q - Contains the same contents as term.
• _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.