Awesome

django-searchable-select

A better and faster multiple selection widget with suggestions for Django

This project is looking for maintainers!

Please open an issue to request write access.

What is this?

This plugin provides a replacement for standard multi-choice select on Django admin pages.

You can use this as custom widget for ManyToManyField.

Features

Filtering is performed on server side and thus significantly improves performance.
Uses Twitter Typeahead to provide suggestion completion.
Works great with ManyToMany fields that can be chosen from thousands of thousands of choices, e. g. User - City relations.

Before

After

Before

Installation

Install django-searchable-select.
```
$ pip install django-searchable-select
```

Add 'searchableselect' to your settings.

# settings.py

INSTALLED_APPS = (
    # ...
    'searchableselect',
    # ...
)

Add URL pattern required for the suggesting engine to your root urls.py.

# urls.py

urlpatterns = patterns(
    '',
    # ...
    url('^searchableselect/', include('searchableselect.urls')),
    # ...
)

Use the widget in your model admin class:

from django import models, forms
from searchableselect.widgets import SearchableSelect
from models import Traveler

class TravelerForm(forms.ModelForm):
    class Meta:
        model = Traveler
        exclude = ()
        widgets = {
            'cities_visited': SearchableSelect(model='cities.City', search_field='name', many=True, limit=10)
        }


class TravelerAdmin(admin.ModelAdmin):
    form = TravelerForm

admin.site.register(Traveler, TravelerAdmin)

Remember to always initialize SearchableSelect with three keyword arguments: model, search_field and many.

model is the string in form APP_NAME.MODEL_NAME representing your model in the project, e. g. 'cities.City'
search_field is the field within model that will be used to perform filtering, e. g. 'name'
many must be True for ManyToManyField and False for ForeignKey.
limit (optional) specifies the maximum count of entries to retrieve.

Example app

Just run the project from example directory, head to http://127.0.0.1:8000, login as admin/admin and try adding Cats!

Supported versions

Python 2.7.x: Django 1.7, 1.8, 1.9, 1.10
Python 3.x: Django 1.8, 1.9, 1.10, 2.0

Testing

In order to support multiple Django and Python versions we use:

py.test - test runner
tox - handy tool to test app with different versions of Pythons & libraries
selenium
coverage

Install them via pip install -r requirements/dev.txt

To test things in specific environment, run the following commands:

# Clear previous coverage data.
coverage erase

# This command can be ran multiple times.
tox -e <python_ver>-<django_ver>
# Possible python_ver values: `py27`, `py36`
# Possible django_ver values: `17`, `18`, `19`, `110`, '20'
# Values can be comma-separated, e. g. `-e py27-17,py27-18,py36-18`
# If you omit `-e ...` parameter, all environments will be tests.
# Also - not problems with running this within a virtualenv.
# Check tox.ini for these values.

# Run this once all tests passed on all environment.
coverage combine

# Render HTML with coverage info.
coverage html
# ...or simply display % of covered SLOC for each file.
coverage report

To add a new Django version for testing, add it into tox.ini, lines 3-4.

Why do we need tox and coverage combine? Because different versions of Python & libraries lead to different code execution: for example, consider this code:

import sys
if sys.version_info.major == 2:
    foo = 'spam'  # Not covered in Python 3.x, leads to coverage < 100%
else:
    foo = 'eggs'  # Not covered in Python 2.x, leads to coverage < 100%

Using tox and coverage combine we're able to "merge" coverage info from across different environments.

Known issues

Not tested with empty fields.
Tests sometimes fail randomly due to some Selenium timeout issue. Weird.

Contributing

I'm looking forward to bug reports and any kind of contribution.

License

You are free to use this where you want as long as you keep the author reference. Please see LICENSE for more info.