skip to navigation
skip to content

Not Logged In

django-selectable-select2 0.2.1

plugin for django-selectable (to use with select2 UI)

Latest Version: 0.3.0

Warning

This is still a work in progress. Some backwards incompatible changes may happen between releases.

This project is a kind of a plugin for django-selectable.

It provides widgets for use with a great JS library called select2 rather than jQuery UI. It also provides it's own Lookup classes for better (IMO) serialization results and limiting results (on server side).

For now there's only a basic single-valued autocomplete widget for usage on ForeignKey (or simply ModelChoiceField) fields.

Installation

  • install django-selectable (you can ommit the part regarding jquery-ui)

  • install django-selectable-select2 like so:

    pip install django-selectable-select2
    
  • add selectable_select2 to INSTALLED_APPS. So it look like this:

    INSTALLED_APPS = (
        ...
        'selectable',
        'selectable_select2',
        ...
    )
    

Usage

Warning

as for now (until issue #64 is resolved) you should inherit from selectable_select2.base.LookupBase and selectable_select2.base.ModelLookup

  • in your forms you can use selectable_select2.widgets.AutoCompleteSelect2Widget like so:

    from selectable_select2.widgets import AutoCompleteSelect2Widget
    from django import forms
    
    from myapp.models import MyModel  # example model with a ForeignKey called ``myfk``
    from myapp.lookups import MyModelLookup  # the lookup defined in previous step
    
    class MyModelForm(forms.ModelForm):
    
        class Meta:
            model = MyModel
            widgets = {
                'myfk' : AutoCompleteSelect2Widget(MyModelLookup, placeholder='select related item')
            }
    

How to include static assets?

There are at least 2 ways of including static assets to work with django-selectable-select2. Both of them assumes that jQuery is already included.

  • First of all you can use the form's media attribute to include appropriate js and css files. Like so:

    <html>
        <head>
            {{ form.media.css }}
        </head>
    
        <body>
            <form action="." method="post">
                {{ form.as_p }}
                <p><button type="submit">Submit</button></p>
            </form>
    
            <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
            {{ form.media.js }}
        </body>
    </html>
    

    Note

    The {{ form.media.js }} also includes the jquery.django.admin.fix.js to work with django admin panel. You may not need this.

  • Or you can mannually include those assets (assuming you're using django-staticfiles). Like so:

    <html>
        <head>
            <link rel="stylesheet" href="{{ STATIC_URL }}selectable_select2/js/select2.css">
        </head>
    
        <body>
            <form action="." method="post">
                {{ form.as_p }}
                <p><button type="submit">Submit</button></p>
            </form>
    
            <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
            <script type="text/javascript" src="{{ STATIC_URL }}selectable_select2/js/select2.min.js"></script>
            <script type="text/javascript" src="{{ STATIC_URL }}selectable_select2/js/jquery.dj.selectable.select2.js"></script>
        </body>
    </html>
    

Chained selects

There is a way to do chained selects in django-selectable. Check out the docs about chained selects to correctly prepare your lookup classes for this use case (you can skip the javascript part). Django-selectable-select2 provides a helper class to declare dependencies of your chained selects on your form.

So given the lookup, from the above link and assuming that MyModel has ForeignKeys for city and state, your form class can inherit from Select2DependencyModelForm and define select2_deps attribute like this:

from selectable_select2.forms import Select2DependencyModelForm
from django import forms
from selectable_select2.widgets import AutoCompleteSelect2Widget

class ChainedForm(Select2DependencyModelForm):

    select2_deps = (
        ('city', { 'parents' : ['state'] }),
    )

    class Meta:
        model = MyModel
        widgets = {
            'city' : AutoCompleteSelect2Widget(CityLookup, placeholder='select city')
        }

There is also Select2DependencyForm which is suitable for non-model based forms.

Note

Both Select2DependencyModelForm and Select2DependencyForm in selectable_select2.forms module inherit from a general class called Select2DependencyFormMixin which defines one method called apply_select2_deps. Don't hesitate to browse the source of those classes.

select2_deps is a tuple of two-tuples in form ('<fieldname>' : { <options dict> }) where the options dict is a Python dictionary that configurates the dependencies for that field.

Reference for the options dict:

parents
List of field names that are superior for the given field. Like in the above example you can choose a city depending on what state you've chosen. The field can be dependant from more than one parent.
clearonparentchange
Boolean (True/False) that indicates whether a field should be cleared when a user changes the selection/value of one of it's parents.

Check the example project for more details.

TODO

check out TODO.rst

A note about version of select2.js used here

django-selectable-select2 comes bundled with "unstable" version of select2. This version is above commit 7baa3b9e9 (the unstable and unreleased 3.2 version) where you can provide your own function to escape the markup. If you want to use this version (e.g. on other select widgets in your project) do it like this:

<script src="{{ STATIC_URL }}selectable_select2/js/select2.min.js"></script>

See https://github.com/ivaynberg/select2/pull/355 for details.

Credits

A BIG THANK YOU goes to Igor Vaynberg (select2) and Mark Lavin (django-selectable) for their projects, their support and quick response time in resolving my issues.

 
File Type Py Version Uploaded on Size
django-selectable-select2-0.2.1.tar.gz (md5) Source 2012-09-04 23KB
  • Downloads (All Versions):
  • 30 downloads in the last day
  • 124 downloads in the last week
  • 812 downloads in the last month