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.
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)
This is the main method which takes the current request from the user and returns the data which matches their search.
| Parameters: |
|
|---|---|
| Returns: | An iterable set of data of items matching the search term. |
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.
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. |
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. |
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. |
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. |
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. |
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: |
|
|---|---|
| Returns: | The current Page object of results. |
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.
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)