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
+you must register in with django-selectable. All lookups must extend from
``selectable.base.LookupBase`` which defines the API for every lookup.
:return: A string representation of the item to be shown in the search results.
The label can include HTML. For changing the label format on the client side
see :ref:`Advanced Label Formats <advanced-label-formats>`.
.. py:method:: LookupBase.get_item_id(item)
add additional keys you should add them here.
The results of ``get_item_label`` is conditionally escaped to prevent
- Cross Site Scripting (XSS) similar to the templating language.
+ Cross Site Scripting (XSS) similar to the templating language.
If you know that the content is safe and you want to use these methods
to include HTML should mark the content as safe with ``django.utils.safestring.mark_safe``
inside the ``get_item_label`` method.
:param item: An item from the search results.
:return: A dictionary of information for this item to be sent back to the client.
-.. py:method:: LookupBase.paginate_results(request, results, limit)
+There are also some additional methods that you could want to use/override. These
+are for more advanced use cases such as using the lookups with JS libraries other
+than jQuery UI. Most users will not need to override these methods.
+.. py:method:: LookupBase.format_results(self, raw_data, options)
+ Returns a python structure that later gets serialized. This makes a call to
+ :ref:`paginate_results<lookup-paginate-results>` prior to calling
+ :ref:`format_item<lookup-format-item>` on each item in the current page.
+ :param raw_data: The set of all matched results.
+ :param options: Dictionary of ``cleaned_data`` from the lookup form class.
+ :return: A dictionary with two keys ``meta`` and ``data``.
+ The value of ``data`` is an iterable extracted from page_data.
+ The value of ``meta`` is a dictionary. This is a copy of options with one additional element
+ ``more`` which is a translatable "Show more" string
+.. py:method:: LookupBase.paginate_results(results, options)
If :ref:`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 <https://docs.djangoproject.com/en/1.3/topics/pagination/>`_
+ built in pagination. See the Django docs on
+ `pagination <https://docs.djangoproject.com/en/1.3/topics/pagination/>`_
- :param request: The current request object.
:param results: The set of all matched results.
limit: The number of results per page.
+ :param .
:return: The current `Page object <https://docs.djangoproject.com/en/1.3/topics/pagination/#page-objects>`_
+.. py:method:: LookupBase.serialize_results(self, results)
+ Returns serialized results for sending via http. You may choose to override
+ this if you are making use of
+ :param results: a python structure to be serialized e.g. the one returned by :ref:`format_results<lookup-format-results>`
.. literalinclude:: ../example/core/lookups.py
-The syntax for ``search_fields`` is the same as the Django
-`field lookup syntax <http://docs.djangoproject.com/en/1.3/ref/models/querysets/#field-lookups>`_.
+The syntax for ``search_fields`` is the same as the Django
+`field lookup syntax <http://docs.djangoproject.com/en/1.3/ref/models/querysets/#field-lookups>`_.
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
-Below is a larger model lookup example using multiple search fields, filters
-and display options for the `auth.User <https://docs.djangoproject.com/en/1.3/topics/auth/#users>`_
+Below is a larger model lookup example using multiple search fields, filters
+and display options for the `auth.User <https://docs.djangoproject.com/en/1.3/topics/auth/#users>`_
XMLHttpRequest (AJAX) request. This decorator enforces that the lookup can only
be accessed in this way. If the request is not an AJAX request then it will return
a 400 Bad Request response.