Defining Lookups

What are Lookups?

Lookups define the corresponding ajax views used by the auto-completion fields and widgets. They take in the current request and return the JSON needed by the jQuery auto-complete plugin.

Defining a Lookup

django-selectable uses a registration pattern similar to the Django admin. Lookups should be defined in a lookups.py in your application’s module. Once defined you must register in with django-selectable. All lookups must extend from selectable.base.LookupBase which defines the API for every lookup.

from selectable.base import LookupBase
from selectable.registry import registry

class MyLookup(LookupBase):
    def get_query(self, request, term):
        data = ['Foo', 'Bar']
        return filter(lambda x: x.startswith(term), data)

registry.register(MyLookup)

Lookup API

LookupBase.get_query(request, term)

This is the main method which takes the current request from the user and returns the data which matches their search.

Parameters:
  • request – The current request object.
  • term – The search term from the widget input.
Returns:

An iterable set of data of items matching the search term.

LookupBase.get_item_label(item)

This is first of three formatting methods. The label is shown in the drop down menu of search results. This defaults to item.__unicode__.

Parameters:item – An item from the search results.
Returns:A string representation of the item to be shown in the search results.

New in version 0.3.

The label can include HTML. For changing the label format on the client side see Advanaced Label Formats.

LookupBase.get_item_id(item)

This is second of three formatting methods. The id is the value that will eventually be returned by the field/widget. This defaults to item.__unicode__.

Parameters:item – An item from the search results.
Returns:A string representation of the item to be returned by the field/widget.
LookupBase.get_item_value(item)

This is last of three formatting methods. The value is shown in the input once the item has been selected. This defaults to item.__unicode__.

Parameters:item – An item from the search results.
Returns:A string representation of the item to be shown in the input.
LookupBase.get_item(value)

get_item is the reverse of get_item_id. This should take the value from the form initial values and return the current item. This defaults to simply return the value.

Parameters:value – Value from the form inital value.
Returns:The item corresponding to the initial value.
LookupBase.create_item(value)

If you plan to use a lookup with a field or widget which allows the user to input new values then you must define what it means to create a new item for your lookup. By default this raises a NotImplemented error.

Parameters:value – The user given value.
Returns:The new item created from the item.
LookupBase.format_item(item)

By default format_item creates a dictionary with the three keys used by the UI plugin: id, value, label. These are generated from the calls to get_item_id, get_item_value, and get_item_label. If you want to add additional keys you should add them here.

Parameters:item – An item from the search results.
Returns:A dictionary of information for this item to be sent back to the client.
LookupBase.paginate_results(request, results, limit)

If SELECTABLE_MAX_LIMIT is defined or limit is passed in request.GET then paginate_results will return the current page using Django’s built in pagination. See the Django docs on pagination for more info.

Parameters:
  • request – The current request object.
  • results – The set of all matched results.
  • limit – The number of results per page.
Returns:

The current Page object of results.

Lookups Based on Models

Perhaps the most common use case is to define a lookup based on a given Django model. For this you can extend selectable.base.ModelLookup. To extend ModelLookup you should set two class attributes: model and search_fields.

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

The syntax for search_fields is the same as the Django field lookup syntax. Each of these lookups are combined as OR so any one of them matching will return a result. You may optionally define a third class attribute filters which is a dictionary of filters to be applied to the model queryset. The keys should be a string defining a field lookup and the value should be the value for the field lookup. Filters on the other hand are combined with AND.

New in version 0.3.

Prior to version 0.3 the model based lookups used a single string search_field. This will continue to work in v0.3 but will raise a DeprecationWarning. This support will be removed in v0.4.

User Lookup Example

Below is a larger model lookup example using multiple search fields, filters and display options for the auth.User model.

from django.contrib.auth.models import User
from selectable.base import ModelLookup
from selectable.registry import registry


class UserLookup(ModelLookup):
    model = User
    search_fields = (
        'username__icontains',
        'first_name__icontains',
        'last_name__icontains',
    )
    filters = {'is_active': True, }

    def get_item_value(self, item):
        # Display for currently selected item
        return item.username

    def get_item_label(self, item):
        # Display for choice listings
        return u"%s (%s)" % (item.username, item.get_full_name())

registry.register(UserLookup)

Project Versions

Table Of Contents

Previous topic

Getting Started

Next topic

Advanced Usage

This Page