Getting Started

The workflow for using django-selectable involves two main parts:
  • Defining your lookups
  • Defining your forms

This guide assumes that you have a basic knowledge of creating Django models and forms. If not you should first read through the documentation on defining models and using forms.

Including jQuery & jQuery UI

The widgets in django-selectable define the media they need as described in the Django documentation on Form Media. That means to include the javascript and css you need to make the widgets work you can include {{ form.media.css }} and {{ form.media.js }} in your template. This is assuming your form is called form in the template context. For more information please check out the Django documentation.

The jQuery and jQuery UI libraries are not included in the distribution but must be included in your templates. See the example project for an example using these libraries from the Google CDN. Django-Selectable should work with jQuery >= 1.4.3 and jQuery UI >= 1.8

<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script>
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jqueryui/1.8.13/jquery-ui.min.js"></script>
{{ form.media.js }}

You must also include a jQuery UI theme stylesheet. In the example project we’ve included the “lightness” theme via the Google CDN.

<link rel="stylesheet" href="//ajax.googleapis.com/ajax/libs/jqueryui/1.8.13/themes/ui-lightness/jquery-ui.css" type="text/css" />
{{ form.media.css }}

Defining a Lookup

The lookup classes define the backend views. The most common case is defining a lookup which searchs models based on a particular field. Let’s define a simple model:

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

    def __unicode__(self):
        return self.name

In a lookups.py we will define our lookup:

class FruitLookup(ModelLookup):
    model = Fruit
    search_fields = ('name__icontains', )

This lookups extends selectable.base.ModelLookup and defines two things: one is the model on which we will be searching and the other is the field which we are searching. This syntax should look familiar as it is the same as the field lookup syntax for making queries in Django.

Below this definition we will register our lookup class.

registry.register(FruitLookup)

Defining Forms

Now that we have a working lookup we will define a form which uses it:

class FruitForm(forms.Form):
    autocomplete = forms.CharField(
        label='Type the name of a fruit (AutoCompleteWidget)',
        widget=selectable.AutoCompleteWidget(FruitLookup),
        required=False,
    )

This replaces the default widget for the CharField with the AutoCompleteWidget. This will allow the user to fill this field with values taken from the names of existing Fruit models.

And that’s pretty much it. Keep on reading if you want to learn about the other types of fields and widgets that are available as well as defining more complicated lookups.

Project Versions

Table Of Contents

Previous topic

Overview

Next topic

Defining Lookups

This Page