dep/django-selectable/docs/widgets.rst

   1 Widgets
   2 ==========
   3
   4 Below are the custom widgets defined by Django-Selectable. All widgets take the
   5 lookup class as the first required argument.
   6
   7 These widgets all support a ``query_params`` keyword argument which is used to pass
   8 additional query parameters to the lookup search. See the section on
   9 :ref:`Adding Parameters on the Server Side <server-side-parameters>` for more
  10 information.
  11
  12 You can configure the plugin options by passing the configuration dictionary in the ``data-selectable-options``
  13 attribute. The set of options availble include those define by the base
  14 `autocomplete plugin <http://api.jqueryui.com/1.9/autocomplete/>`_ as well as the
  15 :ref:`javascript-removeIcon`, :ref:`javascript-comboboxIcon`, and :ref:`javascript-highlightMatch` options
  16 which are unique to django-selectable.
  17
  18     .. code-block:: python
  19
  20         attrs = {'data-selectable-options': {'highlightMatch': True, 'minLength': 5}}
  21         selectable.AutoCompleteSelectWidget(lookup_class=FruitLookup, attrs=attrs)
  22
  23
  24 .. _AutoCompleteWidget:
  25
  26 AutoCompleteWidget
  27 --------------------------------------
  28
  29 Basic widget for auto-completing text. The widget returns the item value as defined
  30 by the lookup ``get_item_value``. If the ``allow_new`` keyword argument is passed as
  31 true it will allow the user to type any text they wish.
  32
  33 .. _AutoComboboxWidget:
  34
  35 AutoComboboxWidget
  36 --------------------------------------
  37
  38 Similar to :ref:`AutoCompleteWidget` but has a button to reveal all options.
  39
  40
  41 .. _AutoCompleteSelectWidget:
  42
  43 AutoCompleteSelectWidget
  44 --------------------------------------
  45
  46 Widget for selecting a value/id based on input text. Optionally allows selecting new items to be created.
  47 This widget should be used in conjunction with the :ref:`AutoCompleteSelectField` as it will
  48 return both the text entered by the user and the id (if an item was selected/matched).
  49
  50 :ref:`AutoCompleteSelectWidget` works directly with Django's
  51 `ModelChoiceField <https://docs.djangoproject.com/en/stable/ref/forms/fields/#modelchoicefield>`_.
  52 You can simply replace the widget without replacing the entire field.
  53
  54     .. code-block:: python
  55
  56         class FarmAdminForm(forms.ModelForm):
  57
  58             class Meta(object):
  59                 model = Farm
  60                 widgets = {
  61                     'owner': selectable.AutoCompleteSelectWidget(lookup_class=FruitLookup),
  62                 }
  63
  64 The one catch is that you must use ``allow_new=False`` which is the default.
  65
  66 ``lookup_class`` may also be a dotted path.
  67
  68     .. code-block:: python
  69
  70          widget = selectable.AutoCompleteWidget(lookup_class='core.lookups.FruitLookup')
  71
  72
  73 .. _AutoComboboxSelectWidget:
  74
  75 AutoComboboxSelectWidget
  76 --------------------------------------
  77
  78 Similar to :ref:`AutoCompleteSelectWidget` but has a button to reveal all options.
  79
  80 :ref:`AutoComboboxSelectWidget` works directly with Django's
  81 `ModelChoiceField <https://docs.djangoproject.com/en/stable/ref/forms/fields/#modelchoicefield>`_.
  82 You can simply replace the widget without replacing the entire field.
  83
  84     .. code-block:: python
  85
  86         class FarmAdminForm(forms.ModelForm):
  87
  88             class Meta(object):
  89                 model = Farm
  90                 widgets = {
  91                     'owner': selectable.AutoComboboxSelectWidget(lookup_class=FruitLookup),
  92                 }
  93
  94 The one catch is that you must use ``allow_new=False`` which is the default.
  95
  96
  97 .. _AutoCompleteSelectMultipleWidget:
  98
  99 AutoCompleteSelectMultipleWidget
 100 --------------------------------------
 101
 102 Builds a list of selected items from auto-completion. This widget will return a list
 103 of item ids as defined by the lookup ``get_item_id``. Using this widget with the
 104 :ref:`AutoCompleteSelectMultipleField` will clean the items to the item objects. This does
 105 not allow for creating new items. There is another optional keyword argument ``postion``
 106 which can take four possible values: `bottom`, `bottom-inline`, `top` or `top-inline`.
 107 This determine the position of the deck list of currently selected items as well as
 108 whether this list is stacked or inline. The default is `bottom`.
 109
 110
 111 .. _AutoComboboxSelectMultipleWidget:
 112
 113 AutoComboboxSelectMultipleWidget
 114 --------------------------------------
 115
 116 Same as :ref:`AutoCompleteSelectMultipleWidget` but with a combobox.