1  MultiSelectDropdown
  2  ===================
  3  A multi select dropdown component with optional search bar
  4  
  5  
  6  Overrides
  7  ---------
  8  
  9  .. function:: format_selected_text(self, count, total)
 10  
 11      This method is called when the selection changes and should return a string.
 12  
 13      The default implementation looks like:
 14  
 15      .. code-block:: python
 16  
 17          from anvil_extras.MultiSelectDropDown import MultiSelectDropDown
 18  
 19          def format_selected_text(self, count, total):
 20              if count > 3:
 21                  return f"{count} items selected"
 22              return ", ".join(self.selected_keys)
 23  
 24  
 25      You can change this by overriding this method.
 26  
 27      You can override it globally by doing the following
 28  
 29      .. code-block:: python
 30  
 31          from anvil_extras.MultiSelectDropDown import MultiSelectDropDown
 32  
 33          def format_selected_text(self, count, total):
 34              if count > 2:
 35                  return f"{count} items selected of {total}"
 36              return ", ".join(self.selected_keys)
 37  
 38          MultiSelectDropdown.format_selected_text = format_selected_text
 39  
 40  
 41      Alternatively you can change the ``count_selected_text`` method per multiselect instance
 42  
 43      .. code-block:: python
 44  
 45          class Form1(Form1Template):
 46              def __init__(self, **properties):
 47                  ...
 48  
 49                  def format_selected_text(count, total):
 50                      if count > 3:
 51                          return f"{count} items selected"
 52                      return ", ".join(self.multi_select_drop_down_1.selected_keys)
 53  
 54                  self.multi_select_drop_down_1.format_selected_text = format_selected_text
 55  
 56  
 57  
 58  Properties
 59  ----------
 60  :align: String
 61  
 62      ``"left"``, ``"right"``, ``"center"``
 63  
 64  :items: Iterable of Strings, Tuples or Dicts
 65  
 66      Strings and tuples as per Anvil's native dropdown component. More control can be added by setting the items to a list of dictionaries.
 67      e.g.
 68  
 69      .. code-block:: python
 70  
 71          self.multi_select_drop_down.items = [
 72              {"key": "1st", "value": 1, "subtext": "pick me"},
 73              {"key": "2nd", "value": 2, "enabled": False},
 74              "---",
 75              {"key": "item 3", "value": 3, "title": "3rd times a charm"},
 76          ]
 77  
 78      The ``"key"`` property is what is displayed in the dropdown.
 79      The ``value`` property is what is returned from the ``selected_values``.
 80  
 81      The remainder of the properties are optional.
 82  
 83      ``"enabled"`` determines if the option is enabled or not - defaults to ``True``.
 84  
 85      ``"title"`` determines what is displayed in the selected box - if not set it will use the value from ``"key"``.
 86  
 87      ``"subtext"`` adds subtext to the dropdown display.
 88  
 89      To create a divider include ``"---"`` at the appropriate index.
 90  
 91  :placeholder: String
 92  
 93      Placeholder when no items have been selected
 94  
 95  :enable_filtering: Boolean
 96  
 97      Allow searching of items by key
 98  
 99  :multiple: Boolean
100  
101      Can also be set to false to disable multiselect
102  
103  :enabled: Boolean
104  
105      Disable interactivity
106  
107  :visible: Boolean
108  
109      Is the component visible
110  
111  :width: String | Number
112  
113      The default width is 200px. This can be set using any css length.
114      Alternatively set the width to be ``"auto"``, which will adjust the width to be as wide as the largest option.
115      ``"fit"`` (or ``"fit-content"``) will size the dropdown depending on what is selected.
116      Use width ``"100%""`` to make the dropdown fill its container.
117  
118  :spacing_above: String
119  
120      One of ``"none"``, ``"small"``, ``"medium"``, ``"large"``
121  
122  :spacing_below: String
123  
124      One of ``"none"``, ``"small"``, ``"medium"``, ``"large"``
125  
126  :selected: Object
127  
128      get or set the current selected values.
129  
130  :enable_select_all: Boolean
131  
132      Enable Select All and Deselect All buttons.
133  
134  
135  Events
136  ------
137  :change:
138  
139      When the selection changes
140  
141  :opened:
142  
143      When the dropdown is opened
144  
145  :closed:
146  
147      When the dropdown is closed
148  
149  :show:
150  
151      When the component is shown
152  
153  :hide:
154  
155      When the component is hidden
156  
157  
158  Styling
159  -------
160  
161  The following variables can be overridden in your theme.css to style the multi select dropdown.
162  
163  .. code-block:: css
164  
165      :root {
166          --ae-ms-option-text: #333333;
167          --ae-ms-option-text-active: #fff;
168          --ae-ms-option-bg-hover: #e8e8e8;
169          --ae-ms-option-bg-active: #337ab7;
170          --ae-ms-option-subtext: #777;
171          --ae-ms-option-subtext-active: rgba(255,255,255,.5);
172      }
173  
174  The following roles can be used to style the multi select dropdown.
175  
176  .. code-block:: css
177  
178      .anvil-role-ae-ms-btn {}
179      .anvil-role-ae-ms-select-btn {}
180      .anvil-role-ae-ms-filter {}
181      .anvil-role-ae-ms-option {}
182      .anvil-role-ae-ms-option-active {}
183      .anvil-role-ae-ms-option-label {}
184      .anvil-role-ae-ms-option-subtext {}
185  
186  The multi select dropdown uses a popover, so additional styling can be done by following the Popover styling guide.