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.