diff --git a/.vscode/settings.json b/.vscode/settings.json
index d69ce88..703353b 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,11 +1,15 @@
{
- "markdown-preview-github-styles.colorTheme": "light",
"editor.rulers": [
88
],
- "python.linting.pylintEnabled": true,
- "python.linting.enabled": true,
- "python.formatting.provider": "black",
+ "[python]": {
+ "editor.defaultFormatter": "ms-python.black-formatter",
+ "editor.tabSize": 4
+ },
+ "editor.formatOnSave": true,
+ "editor.codeActionsOnSave": {
+ "source.organizeImports": "explicit"
+ },
"cSpell.words": [
"htmx",
"textinput"
diff --git a/README.md b/README.md
index 30c335a..da9df57 100644
--- a/README.md
+++ b/README.md
@@ -1,135 +1,230 @@
# django-htmx-autocomplete
-This Django app provides a client-side autocomplete component powered by
+This Django app provides an autocomplete widiget component powered by
[htmx](https://htmx.org/) featuring multiselect, search and is completely extensible.
-
## Quick start
1. Add "autocomplete" to your `INSTALLED_APPS` setting like this:
- ```python
- # settings.py
- INSTALLED_APPS = [
- ...
- 'django.contrib.staticfiles', # also required
- 'autocomplete',
- ]
- ```
+ ```python
+ # settings.py
+ INSTALLED_APPS = [
+ ...
+ 'django.contrib.staticfiles', # also required
+ 'autocomplete',
+ ]
+ ```
1. Include the autocomplete urls like this:
- ```python
- # urls.py
- ...
- from autocomplete import HTMXAutoComplete
-
- urlpatterns = [
- ...
- *HTMXAutoComplete.url_dispatcher('ac'),
- ]
- ```
-
- This will add routes prefixed by `ac` to support component instances.
-
-1. Use either the widget or class to create components!
-
- ```python
- from django forms
- from django.db import models
- from autocomplete import HTMXAutoComplete, widgets
-
- # Example models
- class Person(models.Model):
- name = models.CharField(max_length=60)
-
- class Team(models.Model):
- name = models.CharField(max_length=60)
- members = models.ManyToManyField(Person)
-
- # Using the widget
- class MultipleFormModel(forms.ModelForm):
- """Multiple select example form using a model"""
- class Meta:
- """Meta class that configures the form"""
- model = Team
- fields = ['name', 'members']
- widgets = {
- 'members': widgets.Autocomplete(
- name='members',
- options=dict(multiselect=True, model=Person)
- )
- }
-
- # Using the class
- class GetItemsMultiAutoComplete(HTMXAutoComplete):
- name = "members"
- multiselect = True
-
- class Meta:
- model = Person
-
- ```
+ ```python
+ # urls.py
+ ...
+ from autocomplete import urls as autocomplete_urls
+
+ urlpatterns = [
+ # ...
+ path("ac/", autocomplete_urls),
+ ]
+ ```
+
+1. Create an autocomplete class that extends `autocomplete.ModelAutocomplete`,
+
+ ```python
+ from django forms
+ from django.db import models
+ from autocomplete import Autocomplete, AutocompleteWidget
+
+ class Person(models.Model):
+ name = models.CharField(max_length=60)
+
+ class Team(models.Model):
+ team_lead = models.ForeignKey(
+ Person, null=True, on_delete=models.SET_NULL, related_name="lead_teams"
+ )
+
+ members = models.ManyToManyField(Person)
+
+ class PersonAutocomplete(ModelAutocomplete):
+ model = Person
+ search_attrs = [ 'name' ]
+
+
+ class MultipleFormModel(forms.ModelForm):
+ """Multiple select example form using a model"""
+ class Meta:
+ """Meta class that configures the form"""
+ model = Team
+ fields = ['team_lead', 'members']
+ widgets = {
+ 'team_lead': AutocompleteWidget(
+ ac_class=PersonAutocomplete,
+ ),
+ 'members': AutocompleteWidget(
+ ac_class=PersonAutocomplete,
+ options={"multiselect": True},
+ )
+ }
+ ```
1. Make sure your templates include HTMX.
> **Note**
> Bootstrap is included in this example styling, however it is not required.
- ```django
- {% load autocomplete %}
- {% load static %}
-
-
-
-
-
-
-
-
Example base html template
-
-
-
-
-
-
-
-
- ```
-
-## Customization
-
-### Strings
-
-The strings listed in the table below can be overriden by creating the appropriate
-template in your own project, matching the `autocomplete/strings/{name}.html` pattern.
-By default all strings are available in both French and English.
-
-| Name | Description | Default English | Default French |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
-| no_results | Text displayed when no results are found. | No results found. | Aucun résultat trouvé. |
-| more_results | When `max_results` is set, text displayed when there are additional results available. | Displaying maximum {{ count }} out of {{ total_results }} results. | Affichage maximum de {{ count }} résultats sur {{ total_results }}. |
-| available_results | Text anounced to sceen readers when results are available. If max_results is set, the more_results text is spoken instead. | {{ count }} results available. | {{ count }} résultats disponibles. |
-| nothing_selected | Text anounced to screen readers when there are no selections. | Nothing selected. | Rien de sélectionné. |
-
-Individual instances can override strings by providing a dictionary of `custom_strings`.
+ ```django
+ {% load autocomplete %}
+ {% load static %}
+
+
+
+
+
+
+
+
Example base html template
+
+
+
+
+
+
+
+
+ ```
+
+## Using the widget
+
+- The widget will receive its name, required-ness and disabled-ness from the form field, these work out of the box, including for formsets and prefixed forms.
+- Options that can be tweaked on the fly via widget `options` are,
+ - multiselect
+ - If you want to use the widget in on a multiple-choice field (e.g. a many-to-many field), you can pass an options dict with `multiselect=True` in it
+ - placeholder
+ - default: ""
+ - component_prefix
+ - this is for a niche use-case where you want multiple inputs with the same `name` attribute. In that case and you don't set unique prefixes, the autocomplete widget may not work correctly due to duplicate HTML IDs.
+
+Other options are set less dynamically, by customizing the the autocomplete class...
+
+## Autocomplete class customization
+
+### `minimum_search_length`
+
+default: 3
+
+example:
+
+```python
+class MyAC(Autocomplete):
+ minimum_search_length = 2
+```
+
+### `max_results`
+
+This library does not yet support pagination, but it will efficiently limit results and tell the user there how many results are missing.
```python
- class GetItemsMultiAutoComplete(HTMXAutoComplete):
- name = "members"
- multiselect = True
- custom_strings = {
- "no_results": "no results text",
- "more_results": _("More results text")
- }
+class MyAC(Autocomplete):
+ max_results = 10
+
+```
+
+### `component_prefix`
+
+- In addition to widget options, you can also set the `component_prefix` option on the class itself. Widget options will take precedence over the class.
+- default: ""
+
+### `placeholder`
+
+- In addition to widget options, you can also set the `placeholder` option on the class itself. Widget options will take precedence over the class.
+- default: ""
+
+### Translation strings
+
+You can customize the translation strings used in the autocomplete widget by overriding class variables on your autocomplete class,
+
+- `no_result_text`
+ - default: "No results found."
+- `narrow_search_text`
+ - default: "Showing %(page_size)s of %(total)s items. Narrow your search for more results."
+- `type_at_least_n_characters`
+ - default: "Type at least %(n)s characters"
+
+note that the `%(n)s` and `%(page_size)s` and `%(total)s` are placeholders that will be replaced with the actual values at runtime. If you write your own strings, make sure to use the `%(n)s` rather than `%(n)d`. Variables are converted to strings so the integer formatter will not work.
+
+example:
+
+```python
+class MyAC(Autocomplete):
+ no_result_text = "No results found"
+ narrow_search_text = "Please narrow your search"
+ type_at_least_n_characters = "Type at least %(n)s characters"
+```
+
+### Authentication-aware behaviour
+
+Autocomplete adds 2 new views that any user, including non-authenticated users, can access. Autocomplete classes have a `auth_check` method you can override to add authentication checks. For example, if you want to restrict access to a certain autocomplete to only authenticated users, you can do the following,
+
+```python
+class MyAC(Autocomplete):
+ # ...
+
+ @staticmethod
+ def auth_check(request):
+ if not request.user.is_authenticated:
+ raise PermissionDenied("Must be logged in")
+
+```
+
+This is a common enough use case that we've added a setting shortcut. Add `AUTOCOMPLETE_BLOCK_UNAUTHENTICATED=False` in your settings and all autocomplete views will require authentication by default.
+
+## Non model approach
+
+The model autocomplete is a subclass of the more generic `autocomplete.Autocomplete` class. You can use this class to create an autocomplete that does not rely on a model. There are two important methods to provide,
+
+1. `search_items(cls, search, context)`
+ - Must return an iterable of `{ key: string, label: string }` dictionaries. This iterable must allow slicing and len() to be called on it.
+2. `get_items_from_keys(cls, keys, context)`
+ - Must return a list of `{ key: string, label: string }` dictionaries. This list must be the same length as the input keys list.
+ - This is used to render existing items in the autocomplete widget.
+
+The context argument is a simple namespace type:
+
+```python
+@dataclass
+class ContextArg:
+ request: HttpRequest
+ client_kwargs: django.http.QueryDict
+ # this is a redundant reference to request.GET
+```
+
+We may add additional attributes on this object in the future.
+
+If you're still using models but want different logic than the model-autocomplete, consider cracking open the `ModelAutocomplete` class and seeing how it works. It's probably easier to override its particular methods than to start from scratch and implement an efficient iterable that wraps querysets.
+
+## Tip: Custom Autocomplete base class
+
+If you have several autocompletes in your project, we recommend creating a base autocomplete class that extends `autocomplete.Autocomplete` and using that as your project-wide base class. Here you can customize translation strings, authentication-aware behaviour, min-search-length, max-results-count, etc. This way, you're also insulated from changes in our defaults.
+
+# Contributing
+
+To set up the development environment, follow these steps:
- class Meta:
- model = Person
+```bash
+# from root of project,
+pip install -r requirements.txt
+# running tests,
+python manage.py test tests/
+# running app locally
+python manage.py migrate
+python manage.py runscript sample_app.dev_script
+python manage.py runserver
```
diff --git a/autocomplete/__init__.py b/autocomplete/__init__.py
index 887ea42..4fbca80 100644
--- a/autocomplete/__init__.py
+++ b/autocomplete/__init__.py
@@ -1,4 +1,8 @@
"""
Allow HTMXAutoComplete to be imported from the module directly
"""
-from .autocomplete import HTMXAutoComplete
+
+from .core import Autocomplete, register
+from .shortcuts import ModelAutocomplete
+from .views import urls
+from .widgets import AutocompleteWidget
diff --git a/autocomplete/autocomplete.py b/autocomplete/autocomplete.py
deleted file mode 100644
index d076309..0000000
--- a/autocomplete/autocomplete.py
+++ /dev/null
@@ -1,653 +0,0 @@
-"""
-Django HTMX Autocomplete
-
-This file contains the main functionality of the component.
-"""
-import re
-
-from django.http import (
- HttpResponse,
- HttpResponseBadRequest,
- QueryDict,
- HttpResponseNotFound,
-)
-from django.views import View
-from django.template import loader
-from django.urls import re_path
-from django.core.exceptions import ImproperlyConfigured
-from django.apps import apps
-from django.db import models
-from django.db.models.fields import CharField
-
-# The acceptable regex of the name attribute
-NAME_PATTERN = r"^[a-zA-Z_$][0-9a-zA-Z_$]*$"
-
-
-class HTMXAutoComplete(View):
- """Abstract base class for autocomplete component instances
-
- Create new autocomplete components by extending this class and configuring
- the required parameters. Many of the parameters are verified by the
- `verify_config` class method and will throw errors if not properly
- configured. This mechanism is meant only to assist developers and should
- not be relied upon.
-
- Required attributes:
-
- name (str): The name attribute determines the name of the underlying
- form element and should be unique in your application. It
- will be used as the name of the url pattern and by default
- is appended to the URL of the component's views. The
- uniqueness of the name is not verified, but it must match
- the regex pattern `NAME_PATTERN`.
-
- In simple cases we can link the component to a Django model by adding a
- Meta subclass that defined the model related metadata.
-
- class Meta:
-
- model: A valid Django model or string ('app.model')
-
- Optionally the following attributes can also be defined:
-
- item_value: The column string or DeferredAttribute that will be
- used as the item value. (Defaults to the PK)
-
- item_label: The column string or DeferredAttribute that will be
- used as the item's label and used for searches.
- Defaults to the first CharField, or the first field if
- no CharFields exist.
-
- lookup: Lookup method used for search. This text will be added to
- item_label property to perform searches.
- Defaults to 'icontains'.
-
- For more fine-grained control over what items are available, you can
- also override the `get_items` function.
-
- Note: You must either add a `Meta.model` attribute or override
- `get_items`. If you do both the defined model is accessible via
- `self.Meta.model`, and the `item_value` and `item_label` properties are
- accessible as `self._item_value` and `self._item_label` respectively.
-
- Optional attributes:
-
- label (str or None): The label to use for the component (in HTML)
- If defined it must be a string.
- Defaults to None.
-
- placeholder (str or None): The placeholder text used on the component
- Defaults to None.
-
- indicator (bool): If enabled will display a search indicator.
- Defaults to False
-
- required (bool): If set the control is marked as required.
-
- no_result_text (str): The string displayed when no results are found.
- Defaults to "No results found."
-
- max_results (int): The maximum number of search results to return to the
- frontend, or None for all.
- Defaults to None.
-
- custom_strings (dict): Dictionary containing custom strings to use for this
- instance. Available keys are:
- - no_results The string displayed when no
- results are found.
- - more_results Text to display when the results
- are cut off due to max_results.
- - available_results Text anounced to sceen readers
- when results are available. If
- max_results is set, the
- more_results text is spoken
- instead.
-
- minimum_search_length (int): The minimum search length to perform a search
- and show the dropdown.
- Defaults to 3.
-
- multiselect (boolean): Determines if a user can select multiple items
- from the dropdown, or only 1.
- Defaults to False.
-
- """
-
- # Used for routing and input names. (abstract, must be unique)
- name = None
-
- # If specified use this string instead of name for the route name
- route_name = None
-
- # If specified use this string instead of route_name for the component ID in HTML
- component_id = None
-
- # The component label passed to the template.
- label = None
-
- # The placeholder text. (Typically something like "Type to search...")
- placeholder = None
-
- # If set to True the HTML control will be marked as required
- required = False
-
- # If true the component will be disabled
- disabled = False
-
- # If enabled an indicator will be displayed while waiting for a network response
- indicator = False
-
- # The minimum search length to perform a search and show the dropdown.
- minimum_search_length = 3
-
- # The maximum number of search results to return to the frontend, or None for all
- max_results = None
-
- # Values in this set are stripped from any toggle operation.
- strip_values = set(["undefined"])
-
- # String overrides
- custom_strings = dict()
-
- # If True will allow the user to select multiple items
- multiselect = False
-
- # Used internally to reference the `value` field returned by `get_items`
- _item_value = "value"
-
- # Used internally to reference the `label` field returned by `get_items`
- _item_label = "label"
-
- # Used internally as the field lookup for model searches in `get_items`
- _lookup = "icontains"
-
- @classmethod
- def url_dispatcher(cls, route):
- """Return the url pattern required for the component to function.
-
- Note: Calling this method on the base class returns an array of all
- subclassed url dispatchers.
-
- Calling this method also verifies the configuration of the component.
-
- The following routes will be included in the pattern:
- GET /{route}/{route_name}/items
- GET /{route}/{route_name}/component
- PUT /{route}/{route_name}/toggle
-
- Parameters:
- route (str): The base URL to use when creating the route.
-
- Returns:
- django.urls.URLPattern
- """
- if cls == HTMXAutoComplete:
- return [cls.url_dispatcher(route) for cls in cls.__subclasses__()]
-
- cls.verify_config()
- prefix = f"{route}/{cls.get_route_name()}"
- return re_path(
- f"{prefix}/(?Pitems|component|toggle)$",
- cls.as_view(),
- name=cls.get_route_name(),
- )
-
- @classmethod
- def _verify_label(cls):
- """Test label validity"""
- if (
- hasattr(cls, "label")
- and cls.label is not None
- and not isinstance(cls.label, str)
- ):
- raise ImproperlyConfigured("`label` must be a string.")
-
- @classmethod
- def _verify_name(cls):
- """Test that name is present and valid"""
- if not isinstance(cls.name, str):
- raise ImproperlyConfigured(
- "`name` must a string and defined on the subclass."
- )
-
- if not re.match(NAME_PATTERN, cls.name):
- raise ImproperlyConfigured(
- f"`name` must match the following regex pattern: {NAME_PATTERN}"
- )
-
- @classmethod
- def _verify_route_name(cls):
- """Test that route_name is valid and unique"""
-
- if cls.route_name is not None and not re.match(NAME_PATTERN, cls.route_name):
- raise ImproperlyConfigured(
- f"`route_name` must match regex pattern: {NAME_PATTERN}"
- )
-
- if cls.get_route_name() in [
- cl.get_route_name() if cl is not cls else ""
- for cl in HTMXAutoComplete.__subclasses__()
- ]:
- raise ImproperlyConfigured(
- "Autocomplete components must have a unique route_name. The "
- f"name {cls.get_route_name()}` is already in defined."
- )
-
- @classmethod
- def _verify_component_id(cls):
- """Test that component_id is valid and unique"""
-
- if cls.component_id is not None and not re.match(
- NAME_PATTERN, cls.component_id
- ):
- raise ImproperlyConfigured(
- f"`component_id` must match regex pattern: {NAME_PATTERN}"
- )
-
- if cls.get_component_id() in [
- cl.get_component_id() if cl is not cls else ""
- for cl in HTMXAutoComplete.__subclasses__()
- ]:
- raise ImproperlyConfigured(
- "Autocomplete components must have a unique id. The "
- f"id {cls.get_component_id()}` is already in defined."
- )
-
- @classmethod
- def _verify_model_or_get_items(cls):
- """Test for meta options or get_items"""
- if not hasattr(cls, "Meta") and HTMXAutoComplete.get_items == cls.get_items:
- raise ImproperlyConfigured(
- "You must either define a `Meta` class or override `get_items`"
- )
-
- @classmethod
- def _get_and_verify_model(cls, meta):
- """Test that model is defined and valid
- Returns model object"""
-
- if not hasattr(meta, "model") or meta.model is None:
- raise ImproperlyConfigured("You must set `model` in the `Meta` class.")
- if isinstance(meta.model, str):
- if not "." in meta.model:
- raise ImproperlyConfigured(
- "Meta.model should be an object or string in the format"
- " app.model"
- )
- try:
- return apps.get_model(meta.model)
- except Exception as exp:
- raise ImproperlyConfigured(f"Error loading '{meta.model}'") from exp
- elif not isinstance(meta.model, models.base.ModelBase):
- raise ImproperlyConfigured(
- 'Meta.model should be an object or string in the format "app.model"'
- )
- return meta.model
-
- @classmethod
- def _get_and_verify_item_value(cls, meta):
- """Verify and get item_value"""
- if hasattr(meta, "item_value"):
- if not isinstance(meta.item_value, str) and not isinstance(
- meta.item_value, models.query_utils.DeferredAttribute
- ):
- raise ImproperlyConfigured(
- "If Meta.item_value is defined it must be a valid "
- "column attribute"
- )
- if not isinstance(meta.item_value, str):
- return meta.item_value.field.name
-
- return meta.item_value
-
- return meta.model._meta.pk.name # pylint: disable=protected-access
-
- @classmethod
- def _get_and_verify_item_label(cls, meta):
- if hasattr(meta, "item_label"):
- if not isinstance(meta.item_label, str) and not isinstance(
- meta.item_label, models.query_utils.DeferredAttribute
- ):
- raise ImproperlyConfigured(
- "If Meta.item_label is defined it must be a valid "
- "column attribute"
- )
- if not isinstance(meta.item_label, str):
- return meta.item_label.field.name
- return meta.item_label
-
- all_fields = meta.model._meta.fields # pylint: disable=protected-access
- if len(all_fields) == 0:
- raise ImproperlyConfigured("The chosen model has no fields.")
-
- char_fields = list(filter(lambda x: isinstance(x, CharField), all_fields))
- if len(char_fields) > 0:
- return char_fields[0].name
-
- return all_fields[0].name
-
- @classmethod
- def _get_and_verify_lookup(cls, meta):
- """Get the lookup value"""
- if hasattr(meta, "lookup"):
- if not isinstance(meta.lookup, str):
- raise ImproperlyConfigured(
- "If Meta.lookup is defined it must be a field lookup string"
- )
-
- return meta.lookup
-
- return "icontains"
-
- @classmethod
- def verify_config(cls):
- """Verify that the component is correctly configured.
-
- Raises django.core.exceptions.ImproperlyConfigured
- """
-
- cls._verify_label()
- cls._verify_name()
- cls._verify_route_name()
- cls._verify_component_id()
- cls._verify_model_or_get_items()
-
- if hasattr(cls, "Meta"):
- cls.Meta.model = cls._get_and_verify_model(cls.Meta)
- cls._item_value = cls._get_and_verify_item_value(cls.Meta)
- cls._item_label = cls._get_and_verify_item_label(cls.Meta)
- cls._lookup = cls._get_and_verify_lookup(cls.Meta)
-
- @classmethod
- def get_route_name(cls):
- """Return the name to use for routes
-
- Returns:
- str: Name to use for routes
- """
- return cls.route_name if cls.route_name else cls.name
-
- @classmethod
- def get_component_id(cls, override_id=None):
- """Return the component id used by the template HTML to render the component
-
- Returns:
- str: Component ID
- """
- if override_id:
- return override_id
- return cls.component_id if cls.component_id else cls.get_route_name()
-
- def get_items(self, search=None, values=None):
- """Get available items based on search or values.
-
- If search is specified, only items who's label contain the search
- term will be included in the results. The label column is defined by
- the Meta class's `item_label` attribute.
-
- If values is specified, only items who's value is contained in the
- values array will be included in the results. The value column is
- defined by the Meta class's `item_value` attribute.
-
- This method can be overridden to provide more advanced control over
- how items are searched for or generated. In the case where the Meta
- class is not specified at all, the overridden method is expected to
- return an array of dictionaries where each item has the `label` and
- value` keys defined.
-
- Parameters:
- search (str): The search term
- values (str[]): Array of values
-
- Returns:
- array of dictionaries
- """
- items = None
- if search is not None:
- search_dict = {f"{self._item_label}__{self._lookup}": search}
- # pylint: disable=no-member
- items = self.Meta.model.objects.filter(**search_dict)
-
- if values is not None:
- search_dict = {self._item_value + "__in": values}
- # pylint: disable=no-member
- items = self.Meta.model.objects.filter(**search_dict)
-
- return items.values() if items is not None else []
-
- def map_items(self, items, selected=None):
- """Return an array of dictionaries suitable for use by the templates."""
- return list(
- map(
- lambda o: {
- "label": str(o.get(self._item_label)),
- "value": str(o.get(self._item_value)),
- "selected": str(o.get(self._item_value)) in selected
- if selected
- else False,
- },
- items,
- )
- )
-
- def item_values(self, items, only_selected=False):
- """Returns a list of values.
-
- Typically used to set the form element's value.
-
- only_selected(bool): If set to True only the items with selected=True
- will be used.
- """
- return map(
- lambda x: str(x.get("value")),
- filter(lambda x: not only_selected or x.get("selected"), items),
- )
-
- def put(self, request, method):
- """Handler for PUT /{route}/{name}/toggle
-
- A toggle request should include the item being toggled as well as the
- currently selected items. This is because the response template will
- include an updated list of selected items - and the state of what items
- are selected is stored in the browser. The currently selected items are
- also used to determine if the item is selected or not.
-
- Payload:
- {name} (list): List of values currently "selected".
- item (str): The value of the item being toggled.
-
- Returns:
- HTMX responsible to update selected items displayed in the browser.
- (autocomplete/item.html)
-
- Context:
- name (str): Name of this component (for html elements)
- route_name (str): Name to use to get routes
- component_id (str): ID to use on component
- multiselect (bool): Can the user select multiple items?
- values (list): Updated list of values
- item (dict): The item object being toggled
- selected_items (dict[]): Updated list of selected items
- swap_oob (bool): If True the returned item will be swapped out
- of band. (Used if the user clicks the X on a chip, to
- update the selected style of the option if it is currently
- in the dropdown list)
-
- """
- data = QueryDict(request.body)
- items_selected = data.getlist(self.name)
- override_component_id = data.get("component_id", "")
- component_name = data.get("name", self.name)
-
- if items_selected == [""]:
- items_selected = []
-
- items_selected = [a for a in items_selected if a not in self.strip_values]
-
- if method == "toggle":
- item = data.get("item", None)
- if item is None:
- return HttpResponseBadRequest()
-
- items = self.map_items(
- self.get_items(values=items_selected + [item]), items_selected
- )
-
- def sort_items(item):
- try:
- return items_selected.index(f"{item.get('value')}")
- except ValueError:
- return len(items_selected)
-
- items.sort(key=sort_items)
-
- target_item = next((x for x in items if x.get("value") == item), None)
-
- if target_item is None:
- print("ERROR: Requested item to toggle not found.")
- return HttpResponseNotFound()
-
- if target_item.get("selected"):
- items.remove(target_item)
- target_item["selected"] = False
- else:
- target_item["selected"] = True
-
- if not self.multiselect:
- for item in items:
- if item != target_item:
- item["selected"] = False
-
-
- template = loader.get_template("autocomplete/item.html")
- return HttpResponse(
- template.render(
- {
- "name": component_name,
- "search": "",
- "indicator": self.indicator,
- "placeholder": self.placeholder,
- "required": self.required,
- "custom_strings": self.custom_strings,
- "route_name": self.get_route_name(),
- "component_id": self.get_component_id(override_component_id),
- "multiselect": self.multiselect,
- "values": list(self.item_values(items, True)),
- "item_as_list": [target_item],
- "item": target_item,
- "toggle": items,
- "swap_oob": data.get("remove", False),
- }
- ),
- request,
- )
-
- return HttpResponseBadRequest()
-
- def get(self, request, method):
- """Handler for GET /{route}/{name}/component and /{route}/{name}/items
-
- Common query parameters:
- {name} (list): List of values currently "selected".
-
- GET /{route}/{name}/component
- Renders the component itself.
-
- Returns:
- HTMX responsible to render the root of the component.
- (autocomplete/component.html)
-
- This can be used for initial rendering or to perform live
- updates after events such as on `blur`.
- Notice: The default implementation does not re-render on blur.
-
- Context:
- name (str): Name of this component
- route_name (str): Name to use to get routes
- component_id (str): ID to use in HTML
- label (str): The label of the control (or None)
- placeholder (str): The placeholder text (or None)
- multiselect (bool): Can the user selected multiple items?
- values (list): List of selected values
- selected_items (dict[]): List of selected items
-
- GET /{route}/{name}/items
- Renders the list of items for the dropdown.
-
- Additional query parameters:
- search (str): Search string used to filter the returned items
-
- Returns:
- HTMX responsible to render the list of available items.
-
- Context:
- name (str): Name of this component
- route_name (str): Name to use to get routes
- component_id (str): ID of the component
- search (str): The search string (if any)
- show (bool): Whether or not the dropdown should be shown
- items (dict[]): List of items
- """
- items_selected = request.GET.getlist(self.name)
- if items_selected == [""]:
- items_selected = []
-
- override_component_id = request.GET.get("component_id", "")
- component_name = request.GET.get("name", self.name)
-
- if method == "component":
- template = loader.get_template("autocomplete/component.html")
- selected_options = self.map_items(self.get_items(values=items_selected))
-
- return HttpResponse(
- template.render(
- {
- "name": component_name,
- "disabled": self.disabled,
- "required": self.required,
- "indicator": self.indicator,
- "route_name": self.get_route_name(),
- "component_id": self.get_component_id(override_component_id),
- "label": self.label,
- "placeholder": self.placeholder,
- "multiselect": self.multiselect,
- "values": list(self.item_values(selected_options)),
- "selected_items": list(selected_options),
- "custom_strings": self.custom_strings,
- },
- request,
- )
- )
-
- if method == "items":
- template = loader.get_template("autocomplete/item_list.html")
- search = request.GET.get("search", "")
- show = len(search) >= self.minimum_search_length
- items = (
- self.map_items(self.get_items(search), items_selected) if show else []
- )
- total_results = len(items)
- if self.max_results is not None and len(items) > self.max_results:
- items = items[: self.max_results]
-
- return HttpResponse(
- template.render(
- {
- "name": component_name,
- "required": self.required,
- "placeholder": self.placeholder,
- "indicator": self.indicator,
- "custom_strings": self.custom_strings,
- "multiselect": self.multiselect,
- "route_name": self.get_route_name(),
- "component_id": self.get_component_id(override_component_id),
- "show": show,
- "search": search,
- "items": list(items),
- "total_results": total_results,
- },
- request,
- )
- )
-
- return HttpResponseBadRequest()
diff --git a/autocomplete/core.py b/autocomplete/core.py
new file mode 100644
index 0000000..6a6fcc6
--- /dev/null
+++ b/autocomplete/core.py
@@ -0,0 +1,115 @@
+from dataclasses import dataclass
+
+from django.conf import settings
+from django.core.exceptions import PermissionDenied
+from django.http import HttpRequest
+from django.utils.translation import gettext_lazy as _
+
+# This is the registry of registered autocomplete classes,
+# i.e. the ones who respond to requests
+_ac_registry = {}
+
+
+AC_CLASS_CONFIGURABLE_VALUES = {
+ "disabled",
+ "no_result_text",
+ "narrow_search_text",
+ "minimum_search_length",
+ "max_results",
+ "component_prefix",
+ "placeholder",
+ "indicator",
+}
+
+
+def register(ac_class: type, route_name: str = None):
+ if not route_name:
+ route_name = ac_class.__name__
+
+ ac_class.validate()
+
+ if route_name in _ac_registry:
+ raise ValueError(f"Autocomplete with name '{name}' is already registered.")
+
+ ac_class.route_name = route_name
+
+ _ac_registry[route_name] = ac_class
+
+ return ac_class
+
+
+class Autocomplete:
+
+ no_result_text = _("No results found.")
+ narrow_search_text = _(
+ "Showing %(page_size)s of %(total)s items. Narrow your search for more results."
+ )
+ type_at_least_n_characters = _("Type at least %(n)s characters")
+ minimum_search_length = 3
+ max_results = 100
+ component_prefix = ""
+
+ @classmethod
+ def auth_check(cls, request):
+ """
+ override to inspect request.user or whatever
+ raise a PermissionDenied or SuspiciousOperation exception if needed
+ """
+ if (
+ getattr(settings, "AUTOCOMPLETE_BLOCK_UNAUTHENTICATED", False)
+ and not request.user.is_authenticated
+ ):
+ raise PermissionDenied("Must be logged in to use autocomplete")
+
+ pass
+
+ @classmethod
+ def validate(cls):
+ if not hasattr(cls, "search_items"):
+ raise ValueError("You must implement a search_items method.")
+
+ if not hasattr(cls, "get_items_from_keys"):
+ raise ValueError("You must implement a get_items_from_keys method.")
+
+ @classmethod
+ def map_search_results(cls, items_iterable, selected_keys=None):
+ """
+ This must return a list of dictionaries with the keys "key", "label", and "selected"
+
+ By default, we already expect search_items to return iterable of the form [{"key": "value", "label": "label"}]
+
+ You can override this to consume paginable querysets or whatever
+ """
+
+ return [
+ { # this is the default mapping
+ "key": str(i["key"]),
+ "label": i["label"],
+ "selected": i["key"] in selected_keys or str(i["key"]) in selected_keys,
+ }
+ for i in items_iterable
+ ]
+
+ @classmethod
+ def get_custom_strings(cls):
+ return {
+ "no_results": cls.no_result_text,
+ "more_results": cls.narrow_search_text,
+ "type_at_least_n_characters": cls.type_at_least_n_characters,
+ }
+
+ @classmethod
+ def get_extra_text_input_hx_vals(cls):
+ """
+ returns a dict of key/vals to go in the hx-vals attribute of the text input
+ - must not contain single quotes
+ - to support inline JS expressions, values are not quoted
+ """
+
+ return {}
+
+
+@dataclass
+class ContextArg:
+ request: HttpRequest
+ client_kwargs: dict
diff --git a/autocomplete/locale/en/LC_MESSAGES/django.po b/autocomplete/locale/en/LC_MESSAGES/django.po
index 74c3638..87e3cd1 100644
--- a/autocomplete/locale/en/LC_MESSAGES/django.po
+++ b/autocomplete/locale/en/LC_MESSAGES/django.po
@@ -8,7 +8,7 @@ msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-02-08 20:30+0000\n"
+"POT-Creation-Date: 2024-10-09 09:57-0400\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME \n"
"Language-Team: LANGUAGE \n"
@@ -18,6 +18,22 @@ msgstr ""
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+#: core.py:43
+msgid "No results found."
+msgstr ""
+
+#: core.py:45
+#, python-format
+msgid ""
+"Showing %(page_size)s of %(total)s items. Narrow your search for more "
+"results."
+msgstr ""
+
+#: core.py:47
+#, python-format
+msgid "Type at least %(n)s characters"
+msgstr ""
+
#: templates/autocomplete/strings/available_results.html:2
#, python-format
msgid "%(count)s result available."
@@ -34,26 +50,14 @@ msgstr ""
msgid "%(item)s selected,"
msgstr ""
-#: templates/autocomplete/strings/selected.html:2
-#, python-format
-msgid "selected."
-msgstr ""
-
-#: templates/autocomplete/strings/more_results.html:2
-#, python-format
-msgid "Displaying maximum %(count)s out of %(total_results)s results."
-msgid_plural "Displaying maximum %(count)s out of %(total_results)s results."
-msgstr[0] ""
-msgstr[1] ""
-
-#: templates/autocomplete/strings/multiselect.html:2
+#: templates/autocomplete/strings/multiselect.html:1
msgid "multiselect"
msgstr ""
-#: templates/autocomplete/strings/no_results.html:2
-msgid "No results found."
-msgstr ""
-
#: templates/autocomplete/strings/nothing_selected.html:2
msgid "Nothing selected."
msgstr ""
+
+#: templates/autocomplete/strings/selected.html:2
+msgid "selected."
+msgstr ""
diff --git a/autocomplete/locale/fr/LC_MESSAGES/django.po b/autocomplete/locale/fr/LC_MESSAGES/django.po
index 5786af1..af946d9 100644
--- a/autocomplete/locale/fr/LC_MESSAGES/django.po
+++ b/autocomplete/locale/fr/LC_MESSAGES/django.po
@@ -8,7 +8,7 @@ msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-02-08 20:30+0000\n"
+"POT-Creation-Date: 2024-10-09 09:57-0400\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME \n"
"Language-Team: LANGUAGE \n"
@@ -18,6 +18,22 @@ msgstr ""
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"
+#: core.py:43
+msgid "No results found."
+msgstr "Aucun résultat trouvé."
+
+#: core.py:45
+#, python-format
+msgid ""
+"Showing %(page_size)s of %(total)s items. Narrow your search for more "
+"results."
+msgstr "Seulement %(page_size)s résultats de %(total)s sont affichés. Précisez votre requête pour plus de résultats."
+
+#: core.py:47
+#, python-format
+msgid "Type at least %(n)s characters"
+msgstr "Entrer au moins %(n)s caractères"
+
#: templates/autocomplete/strings/available_results.html:2
#, python-format
msgid "%(count)s result available."
@@ -27,33 +43,29 @@ msgstr[1] "%(count)s résultats disponibles"
#: templates/autocomplete/strings/backspace_instruction.html:2
msgid "Press backspace to delete the last selected item."
-msgstr "Appuyez sur retour arrière pour supprimer le dernier élément sélectionné."
+msgstr ""
+"Appuyez sur retour arrière pour supprimer le dernier élément sélectionné."
#: templates/autocomplete/strings/item_selected.html:2
#, python-format
msgid "%(item)s selected,"
msgstr "%(item)s sélectionné"
-#: templates/autocomplete/strings/selected.html:2
-#, python-format
-msgid "selected."
-msgstr "sélectionné."
-
-#: templates/autocomplete/strings/more_results.html:2
-#, python-format
-msgid "Displaying maximum %(count)s out of %(total_results)s results."
-msgid_plural "Displaying maximum %(count)s out of %(total_results)s results."
-msgstr[0] "Affichage maximum de %(count)s résultat sur %(total_results)s."
-msgstr[1] "Affichage maximum de %(count)s résultats sur %(total_results)s."
-
-#: templates/autocomplete/strings/multiselect.html:2
+#: templates/autocomplete/strings/multiselect.html:1
msgid "multiselect"
msgstr "sélection multiple"
-#: templates/autocomplete/strings/no_results.html:2
-msgid "No results found."
-msgstr "Aucun résultat trouvé."
-
#: templates/autocomplete/strings/nothing_selected.html:2
msgid "Nothing selected."
msgstr "Rien de sélectionné."
+
+#: templates/autocomplete/strings/selected.html:2
+msgid "selected."
+msgstr "sélectionné."
+
+#, python-format
+#~ msgid "Displaying maximum %(count)s out of %(total_results)s results."
+#~ msgid_plural ""
+#~ "Displaying maximum %(count)s out of %(total_results)s results."
+#~ msgstr[0] "Affichage maximum de %(count)s résultat sur %(total_results)s."
+#~ msgstr[1] "Affichage maximum de %(count)s résultats sur %(total_results)s."
diff --git a/autocomplete/shortcuts.py b/autocomplete/shortcuts.py
new file mode 100644
index 0000000..70e71ac
--- /dev/null
+++ b/autocomplete/shortcuts.py
@@ -0,0 +1,96 @@
+import operator
+from functools import reduce
+
+from django.db.models import Q
+
+from .core import Autocomplete
+
+
+class ModelAutocomplete(Autocomplete):
+ model = None
+ search_attrs = []
+
+ @classmethod
+ def get_search_attrs(cls):
+ if not cls.search_attrs:
+ raise ValueError("ModelAutocomplete must have search_attrs")
+ return cls.search_attrs
+
+ @classmethod
+ def get_model(cls):
+ if not cls.model:
+ raise ValueError("ModelAutocomplete must have a model")
+
+ return cls.model
+
+ @classmethod
+ def get_queryset(cls):
+ return cls.get_model().objects.all()
+
+ @classmethod
+ def get_label_for_record(cls, record):
+ return str(record)
+
+ @classmethod
+ def get_query_filtered_queryset(cls, search, context):
+ base_qs = cls.get_queryset()
+ conditions = [
+ Q(**{f"{attr}__icontains": search}) for attr in cls.get_search_attrs()
+ ]
+ condition_filter = reduce(operator.or_, conditions)
+ queryset = base_qs.filter(condition_filter)
+ return queryset
+
+ @classmethod
+ def search_items(cls, search, context):
+ filtered_queryset = cls.get_query_filtered_queryset(search, context)
+
+ items = QuerysetMappedIterable(
+ queryset=filtered_queryset, label_for_record=cls.get_label_for_record
+ )
+ return items
+
+ @classmethod
+ def get_items_from_keys(cls, keys, context):
+ queryset = cls.get_queryset()
+ results = queryset.filter(id__in=keys)
+
+ return [{"key": person.id, "label": person.name} for person in results]
+
+
+class QuerysetMappedIterable:
+ """
+ We want to return an iterable of dicts rather than ORM records
+
+ Using a list is inefficient for large datasets
+ But using something like a generator/map doesn't allow for slicing or len()
+
+ This class wraps a queryset's slice/len methods
+ """
+
+ def __init__(self, queryset, label_for_record):
+ self.queryset = queryset
+ self.label_for_record = label_for_record
+
+ def __getitem__(self, key):
+ # Handle both single index and slice objects
+ if isinstance(key, int):
+ records = [self.queryset[key]]
+ elif isinstance(key, slice):
+ records = self.queryset[key.start : key.stop : key.step]
+ else:
+ raise TypeError("Invalid argument type")
+
+ mapped = [
+ {"key": record.id, "label": self.label_for_record(record)}
+ for record in records
+ ]
+
+ if isinstance(key, int):
+ return mapped[0]
+
+ return mapped
+
+ def __len__(self):
+ # Return the length of the sequence
+ return self.queryset.count()
diff --git a/autocomplete/static/autocomplete/js/autocomplete.js b/autocomplete/static/autocomplete/js/autocomplete.js
index 27de1a5..1750353 100644
--- a/autocomplete/static/autocomplete/js/autocomplete.js
+++ b/autocomplete/static/autocomplete/js/autocomplete.js
@@ -364,3 +364,62 @@ function phac_aspc_autocomplete_keydown_handler(event) {
phac_aspc_autocomplete_clear_focus(container, true);
return true;
}
+
+class AbstractAutocompleteHelper {
+ /*
+ this is a helper class to manipulate autocomplete components
+ creating instances has zero side-effects
+ it's assumed you may instantiate the same component multiple times
+ */
+ constructor(fieldName, componentPrefix="") {
+ this.fieldName = fieldName;
+ this.componentPrefix = componentPrefix;
+ }
+ getComponentId(){
+ return this.componentPrefix + this.fieldName;
+ }
+ getContainer(){
+ return document.getElementById(`${this.getComponentId()}__container`);
+ }
+ getInput(){
+ return this.getContainer().querySelector(`#${this.getComponentId()}__textinput`);
+ }
+ getInputWrapper(){
+ return this.getContainer().querySelector(`#${this.getComponentId()}`);
+ }
+ getResultItems(){
+ return this.getContainer().querySelector(`#${this.getComponentId()}__items`);
+ }
+ getInfo(){
+ return this.getContainer().querySelector(`#${this.getComponentId()}__info`);
+ }
+ getDataContainer(){
+ return this.getContainer().querySelector(`#${this.getComponentId()}__data`);
+ }
+ // behavioral methods
+ clear(){
+ this.getInput().value = '';
+ this.getInputWrapper().innerHTML = '';
+ this.getResultItems().innerHTML = '';
+ this.getInfo().innerHTML = '';
+ this.getDataContainer().removeAttribute('data-phac-aspc-autocomplete');
+ }
+}
+
+class SingleAutocompleteHelper extends AbstractAutocompleteHelper {}
+
+class MultiAutocompleteHelper extends AbstractAutocompleteHelper {
+ getSrDescription(){
+ return this.getContainer().querySelector(`#${this.getComponentId()}__sr_description`);
+ }
+
+ getChips(){
+ return this.getContainer().querySelectorAll(`#${this.getComponentId()}_ac_container li.chip`);
+ }
+
+ clear(){
+ super.clear();
+ this.getChips().forEach(chip => chip.remove());
+ this.getSrDescription().innerHTML = '';
+ }
+}
\ No newline at end of file
diff --git a/autocomplete/templates/autocomplete/chip.html b/autocomplete/templates/autocomplete/chip.html
index 6116f79..63edc77 100644
--- a/autocomplete/templates/autocomplete/chip.html
+++ b/autocomplete/templates/autocomplete/chip.html
@@ -1,3 +1,5 @@
+{% load autocomplete %}
+
{% comment %}
This template renders a selected item or chip.
{% endcomment %}
@@ -6,9 +8,13 @@
{{ item.label }}
{% if not disabled %}
(function () {
const { componentid, css, js, toggleurl } = document.currentScript.dataset;
diff --git a/autocomplete/templates/autocomplete/item.html b/autocomplete/templates/autocomplete/item.html
index e14bea0..c0134f6 100644
--- a/autocomplete/templates/autocomplete/item.html
+++ b/autocomplete/templates/autocomplete/item.html
@@ -2,17 +2,20 @@
{{ item.label|search_highlight:search }}
diff --git a/autocomplete/templates/autocomplete/item_list.html b/autocomplete/templates/autocomplete/item_list.html
index 1fc8b45..2405c12 100644
--- a/autocomplete/templates/autocomplete/item_list.html
+++ b/autocomplete/templates/autocomplete/item_list.html
@@ -1,6 +1,7 @@
{% load autocomplete %}