Widgets

Below are the custom widgets defined by Django-Selectable. All widgets take the lookup class as the first required argument.

These widgets all support a query_params keyword argument which is used to pass additional query parameters to the lookup search. See the section on Adding Parameters on the Server Side for more information.

You can configure the plugin options by passing the configuration dictionary in the data-selectable-options attribute. The set of options availble include those define by the base autocomplete plugin as well as the removeIcon, comboboxIcon, and highlightMatch options which are unique to django-selectable.

attrs = {'data-selectable-options': {'highlightMatch': True, 'minLength': 5}}
selectable.AutoCompleteSelectWidget(lookup_class=FruitLookup, attrs=attrs)

AutoCompleteWidget

Basic widget for auto-completing text. The widget returns the item value as defined by the lookup get_item_value. If the allow_new keyword argument is passed as true it will allow the user to type any text they wish.

AutoComboboxWidget

Similar to AutoCompleteWidget but has a button to reveal all options.

AutoCompleteSelectWidget

Widget for selecting a value/id based on input text. Optionally allows selecting new items to be created. This widget should be used in conjunction with the AutoCompleteSelectField as it will return both the text entered by the user and the id (if an item was selected/matched).

AutoCompleteSelectWidget works directly with Django’s ModelChoiceField. You can simply replace the widget without replacing the entire field.

class FarmAdminForm(forms.ModelForm):

    class Meta(object):
        model = Farm
        widgets = {
            'owner': selectable.AutoCompleteSelectWidget(lookup_class=FruitLookup),
        }

The one catch is that you must use allow_new=False which is the default.

lookup_class may also be a dotted path.

widget = selectable.AutoCompleteWidget(lookup_class='core.lookups.FruitLookup')

AutoComboboxSelectWidget

Similar to AutoCompleteSelectWidget but has a button to reveal all options.

AutoComboboxSelectWidget works directly with Django’s ModelChoiceField. You can simply replace the widget without replacing the entire field.

class FarmAdminForm(forms.ModelForm):

    class Meta(object):
        model = Farm
        widgets = {
            'owner': selectable.AutoComboboxSelectWidget(lookup_class=FruitLookup),
        }

The one catch is that you must use allow_new=False which is the default.

AutoCompleteSelectMultipleWidget

Builds a list of selected items from auto-completion. This widget will return a list of item ids as defined by the lookup get_item_id. Using this widget with the AutoCompleteSelectMultipleField will clean the items to the item objects. This does not allow for creating new items. There is another optional keyword argument postion which can take four possible values: bottom, bottom-inline, top or top-inline. This determine the position of the deck list of currently selected items as well as whether this list is stacked or inline. The default is bottom.

AutoComboboxSelectMultipleWidget

Same as AutoCompleteSelectMultipleWidget but with a combobox.