django-selectable / docs / parameters.rst

Full commit

Additional Parameters

The basic lookup is based on handling a search based on a single term string. If additional filtering is needed it can be inside the lookup get_query but you would need to define this when the lookup is defined. While this fits a fair number of use cases there are times when you need to define additional query parameters that won't be know until the either the form is bound or until selections are made on the client side. This section will detail how to handle both of these cases.

How Parameters are Passed

As with the search term the additional parameters you define will be passed in request.GET. Since get_query gets the current request so you will have access to them.

Adding Parameters on the Server Side

Each of the widgets define update_query_parameters which takes a dictionary. The most common way to use this would be in the form __init__.

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

    def __init__(self, *args, **kwargs):
        super(FruitForm, self).__init__(*args, **kwargs)
        self.fields['autocomplete'].widget.update_query_parameters({'foo': 'bar'})

Adding Parameters on the Client Side

There are times where you want to filter the result set based other selections by the user such as a filtering cities by a previously selected state. In this case you will need to bind a prepareQuery to the field. This function should accept the query dictionary. You are free to make adjustments to the query dictionary as needed.

<script type="text/javascript">
    function newParameters(query) { = 'bar';

    $(document).ready(function() {
        $('#id_autocomplete').djselectable('option', 'prepareQuery', newParameters);