Merge pull request #89 from Doist/add-searchable-event-dropdowns

feat(cohort): add searchable event dropdowns

Author: lukemerrett

bitmapist/cohort/__init__.py

@@ -81,6 +81,25 @@
 
 # --- HTML rendering
 
+# Tom Select is vendored (not loaded from a CDN) so the cohort form makes no
+# third-party network calls at runtime and works offline. The assets are inlined
+# into the fragment because the library has no static-serving mechanism of its
+# own -- consumers just embed the string returned by render_html_form(). Note
+# that inline tags still require the host's CSP to permit inline script/style
+# (or that callers pass include_assets=False and load Tom Select themselves).
+_TOM_SELECT_CSS = "tmpl/vendor/tom-select-2.3.1.default.min.css"
+_TOM_SELECT_JS = "tmpl/vendor/tom-select-2.3.1.complete.min.js"
+
+_VENDOR_CACHE: dict[str, str] = {}
+
+
+def _read_vendor_asset(relative_path: str) -> str:
+    if relative_path not in _VENDOR_CACHE:
+        file_path = path.join(path.dirname(path.abspath(__file__)), relative_path)
+        with open(file_path, encoding="utf-8") as f:
+            _VENDOR_CACHE[relative_path] = f.read()
+    return _VENDOR_CACHE[relative_path]
+
 
 def render_html_form(
     action_url,
@@ -97,6 +116,7 @@ def render_html_form(
     num_results: int = 31,
     num_of_rows: int = 12,
     start_date: Optional[str] = None,
+    include_assets: bool = True,
 ):
     """
     Render a HTML form that can be used to query the data in bitmapist.
@@ -111,6 +131,11 @@ def render_html_form(
     :param :select1b What is the current selected filter (extra, optional)
     :param :select2 What is the current selected filter (second)
     :param :select2b What is the current selected filter (extra, optional)
+    :param :include_assets Whether to inline the vendored Tom Select CSS/JS into
+        the fragment. Defaults to `True`. Set to `False` when rendering more than
+        one form on a page, or when the host page already loads Tom Select, to
+        avoid shipping the library more than once. The searchable dropdowns still
+        initialize as long as Tom Select is available on the page.
 
     """
     # mandatory
@@ -141,6 +166,11 @@ def render_html_form(
             num_results=int(num_results),
             num_of_rows=int(num_of_rows),
             start_date=start_date,
+            include_assets=include_assets,
+            tom_select_css=_read_vendor_asset(_TOM_SELECT_CSS)
+            if include_assets
+            else "",
+            tom_select_js=_read_vendor_asset(_TOM_SELECT_JS) if include_assets else "",
         )
     )
 

bitmapist/cohort/tmpl/form_data.mako

@@ -1,3 +1,18 @@
+<%doc>
+    Tom Select 2.3.1 is vendored and inlined (see bitmapist/cohort/tmpl/vendor/)
+    rather than loaded from a CDN, so the cohort form makes no third-party
+    network calls at runtime and works offline.
+
+    Emitting the library is gated on `include_assets` so a caller that renders
+    more than one cohort form on a page (or already loads Tom Select itself)
+    can suppress the duplicated CSS/JS by passing include_assets=False on the
+    later forms. The small initializer below is always emitted and no-ops if
+    the library isn't present.
+</%doc>
+%if include_assets:
+<style>${ tom_select_css | n }</style>
+%endif
+
 <style>
 .cohort_form dd {
     display: inline-block;
@@ -7,6 +22,14 @@
 .cohort_form select {
     max-width: 150px;
 }
+
+/* The event selects are enhanced with Tom Select, which renders its own
+   searchable control. Give that control a usable width. */
+.cohort_form .ts-wrapper {
+    display: inline-block;
+    min-width: 200px;
+    vertical-align: middle;
+}
 </style>
 
 <form action="${ action_url }" method="GET" class="cohort_form">
@@ -83,8 +106,40 @@
     </dl>
 </form>
 
+<%doc>
+    The library is inlined here, after the form markup, so the browser can
+    render the form before parsing/executing ~50KB of JS.
+</%doc>
+%if include_assets:
+<script>${ tom_select_js | n }</script>
+%endif
+
+<script>
+    // Turn the event dropdowns into searchable selects. With hundreds of
+    // bitmapist events, scrolling a native <select> is painful; Tom Select
+    // adds a type-to-filter search box while still submitting the same value.
+    if (typeof TomSelect === 'undefined') {
+        // Library failed to load for some reason; leave the native <select>s
+        // in place rather than throwing.
+        console.warn('Tom Select unavailable; cohort event dropdowns not enhanced.');
+    } else {
+        document.querySelectorAll('.cohort_form .cohort-event-select').forEach(function (el) {
+            // The form fragment may be rendered more than once on a page, so
+            // this initializer can run again over selects that are already
+            // enhanced. Tom Select throws if re-initialized, so skip those.
+            if (el.tomselect) {
+                return;
+            }
+            new TomSelect(el, {
+                maxOptions: null,   // never truncate the filtered list
+                searchField: ['text', 'value'],
+            });
+        });
+    }
+</script>
+
 <%def name="render_options(select_name, selections, current_selection)">
-    <select name="${ select_name }">
+    <select name="${ select_name }" class="cohort-event-select">
         %for option in selections:
             %if option == '---':
                 <option value="" disabled="disabled">----</option>