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.
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_field.

class FruitLookup(ModelLookup):
    model = Fruit
    search_field = 'name__icontains'

The syntax for search_field is the same as the Django field lookup syntax. 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.

Project Versions

Table Of Contents

Previous topic

Getting Started

Next topic

Additional Parameters

This Page