Django Autocomplete Light

https://github.com/yourlabs/django-autocomplete-light
Admin
Django Autocomplete Light is a Django package that provides autocomplete widgets for choice fields,...
Tokens:14,321
Snippets:207
Trust Score:7.9
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install package via pip

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/install.rst

Standard installation command for the package.

```default
pip install django-autocomplete-light
```

--------------------------------

### Install development version

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/install.rst

Install the latest development version directly from the git repository.

```default
pip install -e git+https://github.com/yourlabs/django-autocomplete-light.git#egg=django-autocomplete-light
```

--------------------------------

### Install and run the demo project

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/install.rst

Commands to set up a temporary virtual environment and run the included test project.

```default
cd /tmp
python3 -m venv dal_env
source dal_env/bin/activate
pip install -e git+https://github.com/yourlabs/django-autocomplete-light.git#egg=django-autocomplete-light
cd dal_env/src/django-autocomplete-light/test_project/
pip install -r requirements.txt
./manage.py migrate
./manage.py createsuperuser
./manage.py runserver
# go to http://localhost:8000/admin/ and login
```

--------------------------------

### Install optional dependencies

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/install.rst

Install specific extras for additional functionality like GenericForeignKey or tag support.

```default
pip install django-autocomplete-light[gfk]     # GenericForeignKey support (django-querysetsequence)
pip install django-autocomplete-light[tags]    # django-taggit support
pip install django-autocomplete-light[nested]  # django-nested-admin support
```

--------------------------------

### Install DAL v4 Optional Integrations

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v3_to_v4.rst

Install specific extras required by your project explicitly.

```default
pip install -U "django-autocomplete-light[gfk]<5"
pip install -U "django-autocomplete-light[tags]<5"
pip install -U "django-autocomplete-light[nested]<5"
```

--------------------------------

### Install DAL v4

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v3_to_v4.rst

Use pip to install the core DAL package compatible with version 4.

```default
pip install -U "django-autocomplete-light<5"
```

--------------------------------

### Define a form with linked autocomplete fields

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Initial setup showing a form where src_country depends on src_continent.

```python
class ShippingForm(forms.Form):
    src_continent = forms.ModelChoiceField(
        queryset=Continent.objects.all(),
        widget=autocomplete.ModelSelect2(url='continent-autocomplete'))
    src_country = forms.ModelChoiceField(
        queryset=Country.objects.all(),
        widget=autocomplete.ModelSelect2(
            url='country-autocomplete',
            forward=('src_continent',)))
```

--------------------------------

### Build DAL from source using PEP 517

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v3_to_v4.rst

Use this command to build the package from source instead of relying on legacy setup.py entry points.

```default
python -m build
```

--------------------------------

### Configure autocomplete view for object creation

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Enable on-the-fly object creation by setting create_field and validate_create in the view configuration.

```python
urlpatterns = [
    path(
        'country-autocomplete/',
        CountryAutocomplete.as_view(create_field='name', validate_create=True),
        name='country-autocomplete',
    ),
]
```

--------------------------------

### Implement get_create_option in v5

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v4_to_v5.rst

Pattern for overriding get_create_option using the _should_show_create helper method.

```default
def get_create_option(self, context, q):
    if not self._should_show_create(context, q):
        return []
    return [{'id': q, 'text': 'Create "%s"' % q, 'create_id': True}]
```

--------------------------------

### Configure INSTALLED_APPS for Generic Foreign Key support

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Include dal_queryset_sequence and its bridge package when using Generic Foreign Keys.

```python
INSTALLED_APPS = [
    'dal',
    'dal_alight',
    'dal_queryset_sequence',
    'dal_alight_queryset_sequence',  # bridges the two
    ...
]
```

--------------------------------

### Registering a Simple Autocomplete View

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Simplified registration using AlightQuerySetView directly with a model.

```python
from dal import autocomplete
from your_countries_app.models import Country

urlpatterns = [
    path(
        'country-autocomplete/',
        autocomplete.AlightQuerySetView.as_view(model=Country),
        name='country-autocomplete',
    ),
]
```

--------------------------------

### Implement an AlightQuerySetView

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Create an autocomplete view by subclassing AlightQuerySetView and defining the get_queryset method.

```python
from dal import autocomplete

from your_countries_app.models import Country


class CountryAutocomplete(autocomplete.AlightQuerySetView):
    def get_queryset(self):
        if not self.request.user.is_authenticated:
            return Country.objects.none()

        qs = Country.objects.all()

        if self.q:
            qs = qs.filter(name__istartswith=self.q)

        return qs
```

--------------------------------

### Mix string-based and class-based forwarding

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Demonstrates combining various forwarding strategies in a single widget configuration.

```python
some_field = forms.ModelChoiceField(
        queryset=SomeModel.objects.all(),
        widget=autocomplete.ModelSelect2(
            url='some-autocomplete',
            forward=(
                'f1',  # String based declaration
                 forward.Field('f2'),  # Works the same way as above declaration
                 forward.Field('f3', 'field3'),  # With rename
                 forward.Const(42, 'f4')  # Constant forwarding (see below)
                 )
```

--------------------------------

### Configure on-the-fly object creation in URL patterns

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Set the create_field attribute in the view to enable creating new objects directly from the autocomplete interface.

```python
urlpatterns = [
    path(
        'country-autocomplete/',
        CountryAutocomplete.as_view(create_field='name'),
        name='country-autocomplete',
    ),
]
```

--------------------------------

### Enable creation in AlightListView

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Implement the create method in the view to allow users to submit values not present in the static list.

```python
class FruitAutocomplete(autocomplete.AlightListView):
    def get_list(self):
        return ['apple', 'mango', 'apricot', 'orange']

    def create(self, text):
        return text  # return the stored value
```

--------------------------------

### Configure INSTALLED_APPS for dal_alight

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Add dal_alight to your Django project settings before django.contrib.admin.

```python
INSTALLED_APPS = [
    'dal',
    'dal_alight',
    # 'grappelli',
    'django.contrib.admin',
    ...
]
```

--------------------------------

### Implement AlightListView for static lists

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Define a view inheriting from AlightListView and override get_list to return a list of strings.

```python
class FruitAutocomplete(autocomplete.AlightListView):
    def get_list(self):
        return ['apple', 'mango', 'apricot', 'orange']
```

--------------------------------

### Implement Tag Autocomplete Views

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/taggit.rst

Create autocomplete views for tags by extending AlightTagAutocompleteView or AlightQuerySetView.

```python
from dal import autocomplete

from taggit.models import Tag


class TagAutocomplete(autocomplete.AlightTagAutocompleteView):
    def get_queryset(self):
        if not self.request.user.is_authenticated:
            return Tag.objects.none()

        qs = Tag.objects.all()

        if self.q:
            qs = qs.filter(name__istartswith=self.q)

        return qs
```

```python
class TagAutocomplete(autocomplete.AlightQuerySetView):
    def get_result_value(self, result):
        return result.name
```

--------------------------------

### Registering an Autocomplete View

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Standard URL configuration for a custom autocomplete view class.

```python
from django.urls import path

from your_countries_app.views import CountryAutocomplete

urlpatterns = [
    path(
        'country-autocomplete/',
        CountryAutocomplete.as_view(),
        name='country-autocomplete',
    ),
]
```

--------------------------------

### Configure INSTALLED_APPS

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/install.rst

Add DAL apps to INSTALLED_APPS before django.contrib.admin to ensure template overrides work correctly.

```default
'dal',
'dal_alight',
# 'grappelli',
'django.contrib.admin',
```

--------------------------------

### Override BaseQuerySetView.post() in v5

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v4_to_v5.rst

Implementation pattern for handling POST requests in v5 by utilizing _post() and returning a JsonResponse.

```default
def post(self, request, *args, **kwargs):
    result = self._post(request)
    if isinstance(result, http.HttpResponse):
        return result
    return http.JsonResponse({
        'id': self.get_result_value(result),
        'text': self.get_selected_result_label(result),
    })
```

--------------------------------

### Configure ListAlight widget

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Use the ListAlight widget in a form by pointing it to the registered autocomplete URL.

```python
widget = autocomplete.ListAlight(url='fruit-autocomplete')
```

--------------------------------

### Verify URL Reversal

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use the Django shell to confirm the registered URL can be reversed correctly.

```console
./manage.py shell
In [1]: from django.urls import reverse
In [2]: reverse('country-autocomplete')
Out[2]: '/country-autocomplete/'
```

--------------------------------

### Implement Select2InitialRenderMixin

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v3_to_v4.rst

Include this mixin in custom Select2 widget subclasses to enable built-in initial value rendering.

```default
class MyWidget(Select2InitialRenderMixin, Select2WidgetMixin, forms.Select):
    pass
```

--------------------------------

### Upgrade DAL via pip

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v4_to_v5.rst

Command to upgrade the django-autocomplete-light package.

```default
pip install -U django-autocomplete-light
```

--------------------------------

### Implement AlightGroupListView

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Return tuples of (group_name, item) from get_list to display grouped string results.

```python
class FruitAutocomplete(autocomplete.AlightGroupListView):
    def get_list(self):
        return [
            ('Tropical', 'mango'),
            ('Tropical', 'papaya'),
            ('Temperate', 'apple'),
            ('Temperate', 'pear'),
        ]
```

--------------------------------

### Initialize a ListSelect2 widget

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use the ListSelect2 widget to connect a form field to a registered Select2ListView URL.

```python
widget = autocomplete.ListSelect2(url='country-list-autocomplete')
```

--------------------------------

### Initialize DAL widgets with HTMX

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v3_to_v4.rst

Use this pattern to automatically initialize autocomplete widgets after HTMX content swaps. Ensure this is only used if DAL's automatic handling is insufficient.

```javascript
document.addEventListener('htmx:afterSettle', function (e) {
    if (window.__dal__initialize && window.django && django.jQuery) {
        var $root = django.jQuery(e.detail.elt);
        $root.find('[data-autocomplete-light-function]')
            .addBack('[data-autocomplete-light-function]')
            .excludeTemplateForms()
            .each(window.__dal__initialize);
    }
});
```

--------------------------------

### Register autocomplete URLs

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/gfk.rst

Extends the project's URL patterns using the form's as_urls method.

```python
from .forms import TestForm

urlpatterns = [...]  # your regular url patterns
urlpatterns.extend(TestForm.as_urls())
```

--------------------------------

### Run tests with tox

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/CLAUDE.md

Execute unit or browser-based tests using tox for specific Python and Django versions.

```bash
cd test_project/
tox -e py314-dj52 -- --ignore-glob='**/test_functional.py'           # unit (-n auto)
tox -e py314-dj52 -- --ignore-glob='**/test_units.py' --ignore-glob='**/test_views.py' --ignore-glob='**/test_forms.py'  # browser (-n auto)
BROWSER=firefox tox -e py314-dj52 -- --ignore-glob='**/test_units.py' --ignore-glob='**/test_views.py' --ignore-glob='**/test_forms.py' --splinter-headless
```

--------------------------------

### Update ChoiceCallable import

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v4_to_v5.rst

Correct import path for ChoiceCallable in DAL 5.

```default
from dal.fields import ChoiceCallable
```

--------------------------------

### Configure GenericForeignKeyModelField with custom widgets

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/gfk.rst

Allows specifying custom widgets and views for the GenericForeignKey field.

```python
from dal import autocomplete

class TestForm(autocomplete.FutureModelForm):

    location = autocomplete.GenericForeignKeyModelField(
        model_choice=[(Country,), (City,)],  # Models
        widget=autocomplete.QuerySetSequenceAlight,
        view=autocomplete.AlightQuerySetSequenceView,
    )

    class Meta:
        model = TestModel
```

--------------------------------

### Define a Select2ListView for a list of strings

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Inherit from Select2ListView and implement get_list to return a simple list of strings.

```python
class CountryAutocompleteFromList(autocomplete.Select2ListView):
    def get_list(self):
        return ['France', 'Fiji', 'Finland', 'Switzerland']
```

--------------------------------

### Enable validation for object creation

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Add validate_create=True to the view configuration to ensure full_clean() is executed before saving the new object.

```python
CountryAutocomplete.as_view(create_field='name', validate_create=True)
```

--------------------------------

### Implement Manual Generic Foreign Key Field

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Configure a GenericForeignKeyModelField with an explicit widget and view for custom requirements.

```python
from dal import autocomplete
from dal_alight_queryset_sequence.views import AlightQuerySetSequenceView
from dal_alight_queryset_sequence.widgets import QuerySetSequenceAlight


class TestForm(autocomplete.FutureModelForm):
    location = autocomplete.GenericForeignKeyModelField(
        model_choice=[(Country,), (City,)],
        widget=QuerySetSequenceAlight,
        view=AlightQuerySetSequenceView,
    )

    class Meta:
        model = TestModel
```

--------------------------------

### Rendering autocomplete forms in templates

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Include form media and handle dynamic formset addition via JavaScript when using autocompletes outside the admin.

```default
{% extends 'base.html' %}
{# Don't forget that one ! #}
{% load static %}

{% block content %}
<div>
    <form action="" method="post">
        {% csrf_token %}
        {{ form.as_p }}

        <div style="display: none" class="formset-empty">
            {{ view.formset.empty_form }}
        </div>

        <div class="formset-rows">
            {{ view.formset }}
        </div>

        <span id="add-form" class="button">Add form</span>

        <input type="submit" />
    </form>
</div>
{% endblock %}

{% block footer %}
<script type="text/javascript" src="{% static 'admin/js/vendor/jquery/jquery.js' %}"></script>

{{ form.media }}

<script>
(function($) {
    $('#add-form').click(function() {
        var index = $('#id_inline_test_models-TOTAL_FORMS').val()
        var newForm = $('#id_inline_test_models-__prefix__-DELETE').closest('.formset-empty').clone()
        newForm.find(':input').each(function() {
            for (attr of ['name', 'id'])
                $(this).attr(
                    attr,
                    $(this).attr(attr).replace('__prefix__', index)
                )
        })
        newForm.removeAttr('style').removeClass('formset-empty')
        newForm.insertBefore($(this))
        $('#id_inline_test_models-TOTAL_FORMS').val(
            parseInt($('#id_inline_test_models-TOTAL_FORMS').val()) + 1
        )
        newForm.slideDown()
    })
})($)
</script>
{% endblock %}
```

--------------------------------

### Register Generic Foreign Key URLs

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Register the auto-generated URLs for the form in the project's urls.py file.

```python
from .forms import TestForm

urlpatterns += TestForm.as_urls()
```

--------------------------------

### Define custom widget and initialization script

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Set the autocomplete_function attribute on the widget and register the corresponding function name in JavaScript.

```python
class YourWidget(ModelSelect2):
    autocomplete_function = 'your_autocomplete_function'
```

```javascript
document.addEventListener('dal-init-function', function () {
    yl.registerFunction( 'your_autocomplete_function', function ($, element) {
        var $element = $(element);
        // autocomplete function here
    });
})
```

--------------------------------

### Configure Select2 options via widget attributes

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Pass Select2 configuration options using the attrs dictionary in the widget constructor. Note that setting a placeholder requires an empty option tag.

```python
# Instanciate a widget with a bunch of options for select2:
autocomplete.ModelSelect2(
    url='select2_fk',
    attrs={
        # Set some placeholder
        'data-placeholder': 'Autocomplete ...',
        # Only trigger autocompletion after 3 characters have been typed
        'data-minimum-input-length': 3,
    },
)
```

--------------------------------

### Customizing Autocomplete Widget Attributes

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Configuring search input appearance using the attrs dictionary.

```default
widgets = {
    'birth_country': autocomplete.ModelAlight(
        url='country-autocomplete',
        attrs={
            'class': 'form-control',
            'placeholder': 'Search countries…',
        },
    ),
}
```

--------------------------------

### Implement Taggit Autocomplete View

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Define a custom autocomplete view for Taggit by inheriting from AlightQuerySetView and overriding get_result_value.

```python
from dal import autocomplete
from taggit.models import Tag


class TagAutocomplete(autocomplete.AlightQuerySetView):
    def get_result_value(self, result):
        return result.name

    def get_queryset(self):
        if not self.request.user.is_authenticated:
            return Tag.objects.none()
        qs = Tag.objects.all()
        if self.q:
            qs = qs.filter(name__istartswith=self.q)
        return qs
```

--------------------------------

### Configuring a TabularInline with a custom form

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Apply custom forms to inline model configurations to support autocomplete functionality.

```python
class PersonInline(admin.TabularInline):
    model = Person
    form = PersonForm
```

--------------------------------

### Implementing ForeignKey Autocomplete

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Using ModelAlight for single-select ForeignKey fields in a ModelForm.

```python
from dal import autocomplete
from django import forms


class PersonForm(forms.ModelForm):
    class Meta:
        model = Person
        fields = ('__all__',)
        widgets = {
            'birth_country': autocomplete.ModelAlight(url='country-autocomplete')
        }
```

--------------------------------

### Pre-fill Login Form Fields with JavaScript

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/test_project/templates/admin/login.html

This JavaScript snippet is used within the login template to pre-fill the username and password fields with 'test' values.

```javascript
document.getElementById('id_username').value = 'test';
document.getElementById('id_password').value = 'test';
```

--------------------------------

### Update Imports for Django 1.9 Compatibility

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/CHANGES.txt

Replace the deprecated autocomplete_light import with the shortcuts module to ensure forward compatibility with Django 1.9 and later.

```python
import autocomplete_light
```

```python
from autocomplete_light import shortcuts as al
```

--------------------------------

### Register custom JavaScript initialization

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Register a custom initialization function using yl.registerFunction after the dal-init-function event is triggered.

```javascript
document.addEventListener('dal-init-function', function () {
    yl.registerFunction( 'select2', function ($, element) {
        // autocomplete function here
    });
})
```

--------------------------------

### Implementing ManyToManyField Autocomplete

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Using ModelAlightMultiple for multi-select ManyToMany fields.

```python
widgets = {
    'visited_countries': autocomplete.ModelAlightMultiple(url='country-autocomplete')
}
```

--------------------------------

### Grant add permission to a user

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Ensure users have the necessary permissions to create objects through the autocomplete interface.

```python
permission = Permission.objects.get(name='Can add your-model-name')
user.user_permissions.add(permission)
```

--------------------------------

### Implement opt-groups with Select2GroupListView

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use Select2GroupListView to group autocomplete options under specific headers.

```python
class CountryAutocompleteFromList(autocomplete.Select2GroupListView):
    def get_list(self):
        return [
            (None, ['Mars Colony',]),
            ("Country", ['France', 'Fiji', 'Finland', 'Switzerland'])
        ]
```

--------------------------------

### Automating Form Fields with djhacker

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Using djhacker to override form fields with autocomplete widgets globally.

```python
import djhacker  # pip install djhacker
from django import forms

djhacker.formfield(
    Person.birth_country,
    forms.ModelChoiceField,
    widget=autocomplete.ModelAlight(url='country-autocomplete')
)
```

--------------------------------

### Implement an autocomplete view with forwarded data

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

The view logic to handle incoming forwarded data from the form.

```python
class CountryAutocomplete(autocomplete.Select2QuerySetView):
    def get_queryset(self):
        if not self.request.is_authenticated:
            return Country.objects.none()

        qs = Country.objects.all()

        continent = self.forwarded.get('continent', None)

        if continent:
            qs = qs.filter(continent=continent)

        if self.q:
            qs = qs.filter(name__istartswith=self.q)

        return qs
```

--------------------------------

### Configure TaggitAlight in Forms

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/taggit.rst

Use the TaggitAlight widget in a ModelForm to enable tag autocompletion.

```python
class TestForm(autocomplete.FutureModelForm):
    class Meta:
        model = TestModel
        fields = ('name',)
        widgets = {
            'tags': autocomplete.TaggitAlight(
                'your-taggit-autocomplete-url'
            )
        }
```

--------------------------------

### Implement AlightGroupQuerySetView

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Group QuerySet results by a related field using group_by_related and related_field_name.

```python
class CountryAutocomplete(autocomplete.AlightGroupQuerySetView):
    group_by_related = 'continent'
    related_field_name = 'name'

    def get_queryset(self):
        return Country.objects.all()
```

--------------------------------

### Listen for dal-element-initialized event

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use this event listener to trigger actions like focusing on a specific autocomplete element once it has been initialized.

```javascript
$(document).on("dal-element-initialized", function (e) {
    if (e.detail.element.id === "my_dal_element_id") {
        $("#my_dal_element_id").select2("open").trigger("focus");
    }
});
```

--------------------------------

### Implement Select2 tags mode in v5

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v4_to_v5.rst

Use this configuration when manually overriding or replacing select2.js to support the new tag creation logic.

```javascript
var createTagFn = null;
if (use_tags) {
    createTagFn = function(params) {
        var term = $.trim(params.term);
        if (!term) return null;
        return {id: term, text: term, newTag: true};
    };
}

$element.select2({
    tags: use_tags,
    createTag: createTagFn,
    // keep your other DAL options
});
```

--------------------------------

### Configure ModelSelect2Multiple Widget

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use ModelSelect2Multiple for ManyToMany relations to handle multiple selections.

```python
class Person(models.Model):
    visited_countries = models.ManyToManyField('your_countries_app.country')
```

```python
widgets = {
    'visited_countries': autocomplete.ModelSelect2Multiple(url='country-autocomplete')
}
```

--------------------------------

### Configure Select2 placeholder and clear button

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/upgrade_from_v3_to_v4.rst

Update Select2 initialization to correctly handle required fields and placeholder text. This ensures the clear button behavior matches v4 standards.

```javascript
var isRequired = $element.is('[required]');
var placeholderText = (
    $element.attr('data-placeholder') || (!isRequired ? ' ' : '')
);

$element.select2({
    placeholder: placeholderText,
    allowClear: !isRequired,
    // keep your other DAL options
});
```

--------------------------------

### Autocomplete Selection Event Listener

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/test_project/templates/admin/base_site.html

Handles navigation to a URL when an autocomplete choice is selected by the user.

```javascript
document.addEventListener('autocompleteChoiceSelected', function(ev) { var url = ev.detail.choice.dataset.url if (url) window.location.href = url })
```

--------------------------------

### Implement Automatic Generic Foreign Key Field

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Use AlightGenericForeignKeyModelField to automatically handle Generic Foreign Key lookups in a form.

```python
from dal import autocomplete
from django.contrib.auth.models import Group


class TestForm(autocomplete.FutureModelForm):
    location = autocomplete.AlightGenericForeignKeyModelField(
        model_choice=[
            (Country, 'name'),
            (City, 'name', [('language', 'spoken_language')]),
        ],
    )

    class Meta:
        model = TestModel
```

--------------------------------

### Reusing DAL internal field retrieval logic

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Implement custom forwarding logic by leveraging DAL's internal helper functions.

```javascript
yl.registerForwardHandler("poormans_field_forward",
    function (elem) {
        return yl.getValueFromField(
            yl.getFieldRelativeTo(elem, "some_field"));
    });
```

--------------------------------

### Configure AlightGenericForeignKeyModelField in a form

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/gfk.rst

Uses FutureModelForm to handle non-editable fields. The model_choice parameter defines the models and optional attribute filtering.

```python
from dal import autocomplete  # don't forget to pip install django-autocomplete-light[gfk]

class TestForm(autocomplete.FutureModelForm):

    location = autocomplete.AlightGenericForeignKeyModelField(
        # Model with values to filter, linked with the name field
        model_choice=[(Country, 'country_code', [('language', 'spoken_language'),]),
                      (City, 'name')],
    )

    class Meta:
        model = TestModel
```

--------------------------------

### Create a Select2 QuerySet View

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Defines a view class inheriting from Select2QuerySetView to filter model results based on user input and authentication status.

```python
from dal import autocomplete

from your_countries_app.models import Country


class CountryAutocomplete(autocomplete.Select2QuerySetView):
    def get_queryset(self):
        # Don't forget to filter out results depending on the visitor !
        if not self.request.user.is_authenticated:
            return Country.objects.none()

        qs = Country.objects.all()

        if self.q:
            qs = qs.filter(name__istartswith=self.q)

        return qs
```

--------------------------------

### Registering a ModelAdmin with a custom form

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Use this to enable autocomplete widgets within the Django admin interface for a specific model.

```python
from django.contrib import admin

from your_person_app.models import Person
from your_person_app.forms import PersonForm


class PersonAdmin(admin.ModelAdmin):
    form = PersonForm

admin.site.register(Person, PersonAdmin)
```

--------------------------------

### Configure forward in ModelForm

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/_forward.rst

Use the forward argument within the widget definition to specify which form fields should be sent to the autocomplete view.

```python
class PersonForm(forms.ModelForm):
    continent = forms.ChoiceField(choices=CONTINENT_CHOICES)

    class Meta:
        model = Person
        fields = ('__all__',)
        widgets = {
            'birth_country': autocomplete.ModelAlight(
                url='country-autocomplete',
                forward=['continent'],
            )
        }
```

--------------------------------

### Registering a custom JavaScript forward handler

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Register a custom handler to provide specific values for autocomplete forwarding.

```javascript
// autocompleteElem here is an HTML element for autocomplete field
yl.registerForwardHandler("my_awesome_handler", function (autocompleteElem) {
    return doSomeMagicAndGetValueFromSpace();
});
```

--------------------------------

### Configure ModelSelect2 Widget

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Assign the ModelSelect2 widget to a ForeignKey field within the Form.Meta.widgets dictionary.

```python
from dal import autocomplete

from django import forms


class PersonForm(forms.ModelForm):
    class Meta:
        model = Person
        fields = ('__all__')
        widgets = {
            'birth_country': autocomplete.ModelSelect2(url='country-autocomplete')
        }
```

--------------------------------

### Use AlightListCreateChoiceField in forms

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/alight.rst

Use AlightListCreateChoiceField to validate submitted values when creation is enabled.

```python
from dal import autocomplete


class FruitForm(forms.ModelForm):
    fruit = autocomplete.AlightListCreateChoiceField(
        choice_list=['apple', 'mango', 'apricot', 'orange'],
        widget=autocomplete.ListAlight(url='fruit-autocomplete'),
    )
```

--------------------------------

### Implement opt-groups with custom values

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Provide nested lists or tuples to define both group labels and individual option values within a Select2GroupListView.

```python
class CountryAutocompleteFromList(autocomplete.Select2GroupListView):
    def get_list(self):
        return [
            ([None, None], [['Mars_colony_value', 'Mars Colony']]),
            (
                ['Country_value', 'Country'],
                [
                    ['France_value', 'France'],
                    ['Fiji_value', 'Fiji'],
                    ['Finland_value', 'Finland'],
                    ['Switzerland_value', 'Switzerland']
                ]
            )
        ]
```

--------------------------------

### Forward arbitrary constant values

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Pass a static value to the autocomplete view without requiring a hidden form field.

```python
from dal import forward

class EuropeanShippingForm(forms.Form):
    src_country = forms.ModelChoiceField(
        queryset=Country.objects.all(),
        widget=autocomplete.ModelSelect2(
            url='country-autocomplete',
            forward=(forward.Const('europe', 'continent'),)))
```

--------------------------------

### Admin Search Bar CSS Styling

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/test_project/templates/admin/base_site.html

Defines layout and appearance for the admin search bar and autocomplete input field.

```css
/* push user-tools to the end so the search bar can sit in the middle */ #user-tools { order: 3; } .dal-admin-search { order: 2; display: flex; flex: 1; justify-content: center; align-items: center; padding: 4px 16px; } .dal-admin-search autocomplete-light { display: block; width: 280px; } .dal-admin-search input[slot="input"] { width: 100%; box-sizing: border-box; padding: 5px 10px; border: 1px solid rgba(255, 255, 255, 0.35); border-radius: 4px; background: rgba(255, 255, 255, 0.12); color: #fff; font-size: 13px; } .dal-admin-search input[slot="input"]::placeholder { color: rgba(255, 255, 255, 0.65); } .dal-admin-search input[slot="input"]:focus { outline: none; background: rgba(255, 255, 255, 0.22); border-color: rgba(255, 255, 255, 0.7); }
```

--------------------------------

### Define custom values for Select2ListView

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Provide a list of lists or tuples to map specific values to display text, ensuring consistency between the view and the form field.

```python
class CountryAutocompleteFromList(autocomplete.Select2ListView):
    def get_list(self):
        return [
            ['France_value', 'France'],
            ['Fiji_value', 'Fiji'],
            ['Finland_value', 'Finland'],
            ['Switzerland_value', 'Switzerland']
        ]


def get_choice_list():
    return [
        ['France_value', 'France'],
        ['Fiji_value', 'Fiji'],
        ['Finland_value', 'Finland'],
        ['Switzerland_value', 'Switzerland']
    ]


class CountryForm(forms.ModelForm):
    country = autocomplete.Select2ListChoiceField(
        choice_list=get_choice_list,
        widget=autocomplete.ListSelect2(url='country-list-autocomplete')
    )
```

--------------------------------

### Render custom HTML in Select2 results

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use the data-html attribute on the widget and override get_result_label in the view to return HTML. Ensure all user-provided data is escaped to prevent XSS.

```python
from django.utils.html import format_html

class CountryAutocomplete(autocomplete.Select2QuerySetView):
    def get_result_label(self, result):
        return format_html('<img src="flags/{}.png"> {}', result.name, result.name)


class PersonForm(forms.ModelForm):
    class Meta:
        widgets = {
            'birth_country': autocomplete.ModelSelect2(
                url='country-autocomplete',
                attrs={'data-html': True}
            )
        }
```

--------------------------------

### Define a model with GenericForeignKey

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/gfk.rst

Requires django.contrib.contenttypes.fields.GenericForeignKey. Note the mandatory monkey patch for editable=True on Django 5.1+.

```python
from django.contrib.contenttypes.fields import GenericForeignKey
from django.db import models


class TestModel(models.Model):
    name = models.CharField(max_length=200)
    language = models.CharField(max_length=200)

    content_type = models.ForeignKey(
        'contenttypes.ContentType',
        null=True,
        blank=True,
        editable=False,
    )

    object_id = models.PositiveIntegerField(
        null=True,
        blank=True,
        editable=False,
    )

    location = GenericForeignKey('content_type', 'object_id')
    # required for django 5.1
    location.editable = True

    def __str__(self):
        return self.name
```

--------------------------------

### Django Admin Login Template Structure

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/test_project/templates/admin/login.html

This is the main structure of the Django admin login template, extending the base site and defining various blocks.

```html
{% extends "admin/base\_site.html" %} {% load i18n static %} {% block extrastyle %}{{ block.super }} {{ form.media }} {% endblock %} {% block bodyclass %}{{ block.super }} login{% endblock %} {% block usertools %}{% endblock %} {% block nav-global %}{% endblock %} {% block content_title %}{% endblock %} {% block breadcrumbs %}{% endblock %} {% block content %} {% if form.errors and not form.non_field_errors %} {% if form.errors.items|length == 1 %}{% trans "Please correct the error below." %}{% else %}{% trans "Please correct the errors below." %}{% endif %} {% endif %} {% if form.non_field_errors %} {% for error in form.non_field_errors %} {{ error }} {% endfor %} {% endif %} {% if user.is_authenticated %} {% blocktrans with username=request.user.username trimmed %} You are authenticated as {{ username }}, but are not authorized to access this page. Would you like to login to a different account? {% endblocktrans %} {% endif %} {% csrf_token %} {{ form.username.errors }} {{ form.username.label_tag }} {{ form.username }} {{ form.password.errors }} {{ form.password.label_tag }} {{ form.password }} {% url 'admin_password_reset' as password_reset_url %} {% if password_reset_url %} [{% trans 'Forgotten your password or username?' %}]({{ password_reset_url }}) {% endif %} {% endblock %}
```

--------------------------------

### Integrate autocompletes in Django Admin

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use a custom form within ModelAdmin or TabularInline to enable autocomplete functionality in the admin interface.

```python
from django.contrib import admin

from your_person_app.models import Person
from your_person_app.forms import PersonForm


class PersonAdmin(admin.ModelAdmin):
    form = PersonForm
admin.site.register(Person, PersonAdmin)
```

```python
class PersonInline(admin.TabularInline):
    model = Person
    form = PersonForm
```

--------------------------------

### Configuring a form field to use a custom forward handler

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use the registered JavaScript handler in a Django form field definition.

```python
from dal import forward

class ShippingForm(forms.Form):
    country = forms.ModelChoiceField(
        queryset=Country.objects.all(),
        widget=autocomplete.ModelSelect2(
            url='country-autocomplete',
            forward=(forward.JavaScript('my_awesome_handler', 'magic_number'),)))
```

--------------------------------

### Dynamically Add Inline Formset Form

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/test_project/alight_outside_admin/templates/alight_outside_admin/alight_outside_admin.html

This JavaScript code snippet demonstrates how to dynamically add a new form to an inline formset when a button is clicked. It clones an empty form, updates its input field names and IDs to reflect the new index, and inserts it into the DOM.

```javascript
(function($) {
    $('#add-form').click(function() {
        var index = $('#id_inline_test_models-TOTAL_FORMS').val()
        var newForm = $('#id_inline_test_models-__prefix__-DELETE').closest('.formset-empty').clone()
        newForm.find(':input').each(function() {
            for (attr of ['name', 'id']) {
                $(this).attr(attr, $(this).attr(attr).replace('__prefix__', index))
            }
        })
        newForm.removeAttr('style').removeClass('formset-empty')
        newForm.insertBefore($(this))
        $('#id_inline_test_models-TOTAL_FORMS').val(parseInt($('#id_inline_test_models-TOTAL_FORMS').val()) + 1)
        newForm.slideDown()
    })
})($)
```

--------------------------------

### Use Select2ListChoiceField in a ModelForm

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Integrate the autocomplete widget into a form using Select2ListChoiceField to manage the choice list.

```python
def get_choice_list():
    return ['France', 'Fiji', 'Finland', 'Switzerland']


class CountryForm(forms.ModelForm):
    country = autocomplete.Select2ListChoiceField(
        choice_list=get_choice_list,
        widget=autocomplete.ListSelect2(url='country-list-autocomplete')
    )
```

--------------------------------

### Define a Taggable Model

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/taggit.rst

Use TaggableManager to add tagging functionality to a Django model.

```python
from django.db import models

from taggit.managers import TaggableManager


class TestModel(models.Model):
    name = models.CharField(max_length=200)

    tags = TaggableManager()

    def __str__(self):
        return self.name
```

--------------------------------

### Differentiate selected result labels

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Override get_selected_result_label in the view to display a different label for the selected item compared to the list view.

```python
class CountryAutocomplete(autocomplete.Select2QuerySetView):
    def get_result_label(self, item):
        return item.full_name

    def get_selected_result_label(self, item):
        return item.short_name
```

--------------------------------

### Rename forwarded fields using class-based declaration

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use forward.Field to map a form field name to a different key expected by the view.

```python
from dal import forward

class ShippingForm(forms.Form):
    src_continent = forms.ModelChoiceField(
        queryset=Continent.objects.all(),
        widget=autocomplete.ModelSelect2(url='continent-autocomplete'))
    src_country = forms.ModelChoiceField(
        queryset=Country.objects.all(),
        widget=autocomplete.ModelSelect2(
            url='country-autocomplete',
            forward=(forward.Field('src_continent', 'continent'),)))
```

--------------------------------

### Forward own selected value

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Forward the current field's value to the view, useful for excluding selected items in multiselects.

```python
from dal import forward

class SomeForm(forms.Form):
    countries = forms.ModelMultipleChoiceField(
        queryset=Country.objects.all(),
        widget=autocomplete.ModelSelect2Multiple(
            url='country-autocomplete',
            forward=("countries", )
```

```python
from dal import forward

class SomeForm(forms.Form):
    countries = forms.ModelMultipleChoiceField(
        queryset=Country.objects.all(),
        widget=autocomplete.ModelSelect2Multiple(
            url='country-autocomplete',
            forward=(forward.Self(),)
```

--------------------------------

### Filter queryset using forwarded values in the view

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Access forwarded values via self.forwarded in the Select2QuerySetView to filter the queryset dynamically.

```python
class CountryAutocomplete(autocomplete.Select2QuerySetView):
    def get_queryset(self):
        if not self.request.user.is_authenticated:
            return Country.objects.none()

        qs = Country.objects.all()

        continent = self.forwarded.get('continent', None)

        if continent:
            qs = qs.filter(continent=continent)

        if self.q:
            qs = qs.filter(name__istartswith=self.q)

        return qs
```

--------------------------------

### Access forwarded values in the view

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/_forward.rst

Retrieve forwarded data using self.forwarded in the autocomplete view to filter the queryset dynamically.

```python
class CountryAutocomplete(autocomplete.AlightQuerySetView):
    def get_queryset(self):
        qs = Country.objects.all()
        continent = self.forwarded.get('continent', None)
        if continent:
            qs = qs.filter(continent=continent)
        if self.q:
            qs = qs.filter(name__istartswith=self.q)
        return qs
```

--------------------------------

### Clearing an autocomplete widget on field change

Source: https://github.com/yourlabs/django-autocomplete-light/blob/master/docs/select2.rst

Use jQuery to clear an autocomplete field when a related form field changes.

```javascript
$(document).ready(function() {
    // Bind on continent field change
    $(':input[name$=continent]').on('change', function() {
        // Get the field prefix, ie. if this comes from a formset form
        var prefix = $(this).getFormPrefix();

        // Clear the autocomplete with the same prefix
        $(':input[name=' + prefix + 'birth_country]').val(null).trigger('change');
    });
});
```
Tokens:
Raw