Source

django-selectable / docs / widgets.rst

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 :ref:`Adding Parameters on the Server Side <server-side-parameters>` for more information.

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 :ref:`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 :ref:`AutoCompleteSelectField` as it will return both the text entered by the user and the id (if an item was selected/matched).

Prior to 0.4 :ref:`AutoCompleteSelectWidget` could not work directly with Django's ModelChoiceField. Starting with 0.4 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.

AutoComboboxSelectWidget

Similar to :ref:`AutoCompleteSelectWidget` but has a button to reveal all options.

Prior to 0.4 :ref:`AutoComboboxSelectWidget` could not work directly with Django's ModelChoiceField. Starting with 0.4 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 :ref:`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 :ref:`AutoCompleteSelectMultipleWidget` but with a combobox.