django-select2

To use Select2 in a Django project, follow these steps:

1. Define your Models: Use standard Django models (e.g., a ForeignKey or ManyToManyField).
2. Create Select2 Widgets: In your forms.py, subclass s2forms.ModelSelect2Widget (for single selection) or s2forms.ModelSelect2MultipleWidget (for multiple selection) from django_select2.forms. Define search_fields to specify which model fields are searchable.
3. Configure the Form: In your ModelForm, map the model fields to your custom Select2 widgets in the Meta.widgets dictionary.
4. Render in Template: In your HTML template, you must include {{ form.media.css }} in the <head> and {{ form.media.js }} (usually near the end of the <body>). Note that django-select2 requires jQuery to be present in the page, but it is not bundled with the package.

Note on jQuery: You must manually include jQuery in your template (e.g., via CDN) before {{ form.media.js }}.

# forms.py
from django import forms
from django_select2 import forms as s2forms
from . import models

class AuthorWidget(s2forms.ModelSelect2Widget):
    search_fields = [
        "username__icontains",
        "email__icontains",
    ]

class CoAuthorsWidget(s2forms.ModelSelect2MultipleWidget):
    search_fields = [
        "username__icontains",
        "email__icontains",
    ]

class BookForm(forms.ModelForm):
    class Meta:
        model = models.Book
        fields = "__all__"
        widgets = {
            "author": AuthorWidget,
            "co_authors": CoAuthorsWidget,
        }

<!-- template.html -->
<head>
    {{ form.media.css }}
</head>
<body>
    <form method="POST">
        {% csrf_token %}
        {{ form.as_p }}
        <input type="submit">
    </form>
    <!-- jQuery is required -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    {{ form.media.js }}
</body>

To prevent sensitive data from being accessible to the general public, you can create a secure JSON endpoint for your Select2 widgets.

1. Create a view that inherits from LoginRequiredMixin and AutoResponseView.
2. Create a mixin that sets the data_view attribute to the name of your secure view.
3. Use this mixin in your widget definition.

Additionally, it is recommended to set up a separate cache database for Select2 to mitigate potential Denial of Service (DoS) attacks where an attacker attempts to fill the cache by repeatedly reloading public forms.

class UserSelect2View(LoginRequiredMixin, AutoResponseView):
    pass

class UserSelect2WidgetMixin(object):
    def __init__(self, *args, **kwargs):
        kwargs['data_view'] = 'user-select2-view'
        super(UserSelect2WidgetMixin, self).__init__(*args, **kwargs)

class MySecretWidget(UserSelect2WidgetMixin, ModelSelect2Widget):
    model = MySecretModel
    search_fields = ['title__icontains']

You can create a dependency where the options in one Select2 widget are filtered based on the selection of another. This is achieved using the dependent_fields argument in the ModelSelect2Widget.

Key Details:

• The dependent_fields argument is a dictionary where the key is the name of the field in the Django form, and the value is the name of the field in the model used for the queryset filter.
• Limitation: This feature does not work with the 'light' version (django_select2.forms.Select2Widget).

Example: In an address form, selecting a Country should filter the available City options.

class AddressForm(forms.Form):
    country = forms.ModelChoiceField(
        queryset=Country.objects.all(),
        label="Country",
        widget=ModelSelect2Widget(
            model=Country,
            search_fields=['name__icontains'],
        )
    )

    city = forms.ModelChoiceField(
        queryset=City.objects.all(),
        label="City",
        widget=ModelSelect2Widget(
            model=City,
            search_fields=['name__icontains'],
            dependent_fields={'country': 'country'},  # 'country' is form field, 'country' is model field
            max_results=500,
        )
    )

Interdependent widgets allow two or more fields to influence each other's available options, rather than having a strict parent-child hierarchy. This is useful when you want to suggest options for any field based on the selection in another.

Implementation Note: When setting dependent_fields, the value must correspond to the model's related name or field used in the filter condition. If the model field name differs from the widget field name, use the model's attribute name.

Caution: When using interdependent widgets in a parent-child relationship, selecting a child may restrict the user from changing the parent (as only one value remains valid). It is recommended to allow users to reset the child field to release the parent Select2.

class AddressForm(forms.Form):
    country = forms.ModelChoiceField(
        queryset=Country.objects.all(),
        label="Country",
        widget=ModelSelect2Widget(
            search_fields=['name__icontains'],
            dependent_fields={'city': 'cities'},  # 'cities' is the related_name on the Country model
        )
    )

    city = forms.ModelChoiceField(
        queryset=City.objects.all(),
        label="City",
        widget=ModelSelect2Widget(
            search_fields=['name__icontains'],
            dependent_fields={'country': 'country'},
            max_results=500,
        )
    )