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

Installation

1. Install django-searchable-select.

   $ pip install django-searchable-select

2. Add ‘searchableselect’ to your settings.

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

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

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

4. 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:

<div class="highlight highlight-source-shell position-relative" data-snippet-clipboard-copy-content="# Clear previous coverage data.
coverage erase

# This command can be ran multiple times.
tox -e –
# 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
“>

# 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

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%