Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/PHACDataHub/django-htmx-autocomplete
A Django autocomplete component powered by htmx
https://github.com/PHACDataHub/django-htmx-autocomplete
Last synced: 2 months ago
JSON representation
A Django autocomplete component powered by htmx
- Host: GitHub
- URL: https://github.com/PHACDataHub/django-htmx-autocomplete
- Owner: PHACDataHub
- License: mit
- Created: 2022-11-17T20:39:25.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-17T13:31:41.000Z (3 months ago)
- Last Synced: 2024-10-19T19:07:07.289Z (3 months ago)
- Language: Python
- Size: 157 KB
- Stars: 50
- Watchers: 5
- Forks: 4
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-python-htmx - django-htmx-autocomplete - Django-a9bbcc?style=flat&logo=django&logoColor=black" alt="Django"></a> <br/> (Third Party Packages 📦 <a name = "tools"></a> / Components)
README
# django-htmx-autocomplete
This Django app provides a client-side autocomplete 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',
]
```
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
```
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
document.body.addEventListener('htmx:configRequest', (event) => {
event.detail.headers['X-CSRFToken'] = '{{ csrf_token }}';
});
```
## 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`.
```python
class GetItemsMultiAutoComplete(HTMXAutoComplete):
name = "members"
multiselect = True
custom_strings = {
"no_results": "no results text",
"more_results": _("More results text")
}
class Meta:
model = Person
```