# Django Awesomplete
A django app that provides suggestions while you type into the field.
[](https://pypi.org/project/django-awesomplete/)
[](https://github.com/dldevinc/django-awesomplete)
[](https://pypi.org/project/django-awesomplete/)
## Requirements
- Python >= 3.6
- Django >= 1.11
## Installation
Install the desired version with pip:
```
pip install django-awesomplete
```
Then add awesomplete to INSTALLED_APPS in your settings file:
```python
INSTALLED_APPS = (
# ...
'awesomplete',
# ...
)
```
## Quickstart
Let's assume we are making a cities app in django and our `models.py` is:
```python
from django.db import models
class City(models.Model):
name = models.CharField(max_length=255)
country = models.CharField(max_length=255)
def __str__(self):
return self.name
```
To use suggestions we need to override widget in `admin.py`:
```python
from django import forms
from django.contrib import admin
from awesomplete.widgets import AwesompleteWidgetWrapper
from .models import City
def get_country_suggestions():
"""
Get a suggestions list from existing records.
"""
return City.objects.values_list(
'country',
flat=True
).order_by('country').distinct()
class CityAdminForm(forms.ModelForm):
class Meta:
model = City
fields = forms.ALL_FIELDS
widgets = {
'country': AwesompleteWidgetWrapper(
suggestions=get_country_suggestions
)
}
@admin.register(City)
class CityAdmin(admin.ModelAdmin):
form = CityAdminForm
```
Result:
## Suggestions
You can pass either an iterable of strings, 2-tuples, dicts
or a callable that returns such an iterable.
```python
# iterable of strings
AwesompleteWidgetWrapper(
suggestions=['one', 'two', 'three']
)
# iterable of 2-tuples (value, label)
AwesompleteWidgetWrapper(
suggestions=(
('en', 'English'),
('es', 'Spanish')
)
)
# iterable of dicts
AwesompleteWidgetWrapper(
suggestions=(
{
'label': 'English',
'value': 'en'
},
{
'label': 'Spanish',
'value': 'es'
}
)
)
```
## AwesompleteWidgetWrapper
Actually, `AwesompleteWidgetWrapper` is a wrapper for a widget.
When the `widget` is not defined, it defaults to `TextInput`.
You can specify another widget explicitly, e.g. `EmailInput`:
```python
from django import forms
from awesomplete.widgets import AwesompleteWidgetWrapper
from .models import City
class CityAdminForm(forms.ModelForm):
class Meta:
model = City
fields = forms.ALL_FIELDS
widgets = {
'email': AwesompleteWidgetWrapper(
widget=forms.EmailInput,
min_chars=0,
suggestions=(
'noreply@mail.com',
'dont_disturb@mail.com',
'mayor@mail.com',
'support@mail.com',
),
)
}
```
You can also pass additional parameters to `AwesompleteWidgetWrapper`:
- **`min_chars`**
<br>
Minimum characters the user has to type before the autocomplete
popup shows up.
<br>
_Default_: `1`
- **`max_items`**
<br>
Maximum number of suggestions to display.
<br>
_Default_: `10`
- **`autofirst`**
<br>
Should the first element be automatically selected?
<br>
_Default_: `True`
## AwesompleteTagsWidgetWrapper
This widget is a subclass of the `AwesompleteWidgetWrapper` and intended to be used
for entering comma-separated values.
This widget can be used with [django-taggit](https://github.com/jazzband/django-taggit)
```python
from django import forms
from awesomplete.widgets import AwesompleteTagsWidgetWrapper
from taggit.models import Tag
from taggit.forms import TagWidget
from .models import City
def get_tag_suggestions():
return Tag.objects.values_list(
'name',
flat=True
).order_by('name').distinct()
class CityForm(forms.ModelForm):
class Meta:
model = City
fields = forms.ALL_FIELDS
widgets = {
'tags': AwesompleteTagsWidgetWrapper(
widget=TagWidget,
suggestions=get_tag_suggestions
)
}
```
## Links
- [awesomplete](http://leaverou.github.io/awesomplete/) created by Lea Verou.
## License
Copyright (c) 2018 Mihail Mishakin Released under the BSD license (see LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/dldevinc/django-awesomplete",
"name": "django-awesomplete",
"maintainer": "Mihail Mishakin",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "x896321475@gmail.com",
"keywords": "",
"author": "Mihail Mishakin",
"author_email": "x896321475@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/33/39/24c991b3138e4d7d70f61081d0451d5dfcc1b3106c125f74e54de5a851a6/django-awesomplete-0.6.0.tar.gz",
"platform": "OS Independent",
"description": "# Django Awesomplete\n\nA django app that provides suggestions while you type into the field.\n\n[](https://pypi.org/project/django-awesomplete/)\n[](https://github.com/dldevinc/django-awesomplete)\n[](https://pypi.org/project/django-awesomplete/)\n\n## Requirements\n\n- Python >= 3.6\n- Django >= 1.11\n\n## Installation\n\nInstall the desired version with pip:\n\n```\npip install django-awesomplete\n```\n\nThen add awesomplete to INSTALLED_APPS in your settings file:\n\n```python\nINSTALLED_APPS = (\n # ...\n 'awesomplete',\n # ...\n)\n```\n\n## Quickstart\n\nLet's assume we are making a cities app in django and our `models.py` is:\n\n```python\nfrom django.db import models\n\n\nclass City(models.Model):\n name = models.CharField(max_length=255)\n country = models.CharField(max_length=255)\n\n def __str__(self):\n return self.name\n```\n\nTo use suggestions we need to override widget in `admin.py`:\n\n```python\nfrom django import forms\nfrom django.contrib import admin\nfrom awesomplete.widgets import AwesompleteWidgetWrapper\nfrom .models import City\n\n\ndef get_country_suggestions():\n \"\"\"\n Get a suggestions list from existing records.\n \"\"\"\n return City.objects.values_list(\n 'country',\n flat=True\n ).order_by('country').distinct()\n\n\nclass CityAdminForm(forms.ModelForm):\n class Meta:\n model = City\n fields = forms.ALL_FIELDS\n widgets = {\n 'country': AwesompleteWidgetWrapper(\n suggestions=get_country_suggestions\n )\n }\n\n\n@admin.register(City)\nclass CityAdmin(admin.ModelAdmin):\n form = CityAdminForm\n```\n\nResult:\n\n\n\n## Suggestions\n\nYou can pass either an iterable of strings, 2-tuples, dicts\nor a callable that returns such an iterable.\n\n```python\n# iterable of strings\nAwesompleteWidgetWrapper(\n suggestions=['one', 'two', 'three']\n)\n\n# iterable of 2-tuples (value, label)\nAwesompleteWidgetWrapper(\n suggestions=(\n ('en', 'English'),\n ('es', 'Spanish')\n )\n)\n\n# iterable of dicts\nAwesompleteWidgetWrapper(\n suggestions=(\n {\n 'label': 'English',\n 'value': 'en'\n },\n {\n 'label': 'Spanish',\n 'value': 'es'\n }\n )\n)\n```\n\n## AwesompleteWidgetWrapper\n\nActually, `AwesompleteWidgetWrapper` is a wrapper for a widget.\nWhen the `widget` is not defined, it defaults to `TextInput`.\n\nYou can specify another widget explicitly, e.g. `EmailInput`:\n\n```python\nfrom django import forms\nfrom awesomplete.widgets import AwesompleteWidgetWrapper\nfrom .models import City\n\n\nclass CityAdminForm(forms.ModelForm):\n class Meta:\n model = City\n fields = forms.ALL_FIELDS\n widgets = {\n 'email': AwesompleteWidgetWrapper(\n widget=forms.EmailInput,\n min_chars=0,\n suggestions=(\n 'noreply@mail.com',\n 'dont_disturb@mail.com',\n 'mayor@mail.com',\n 'support@mail.com',\n ),\n )\n }\n```\n\nYou can also pass additional parameters to `AwesompleteWidgetWrapper`:\n\n- **`min_chars`**\n <br>\n Minimum characters the user has to type before the autocomplete\n popup shows up.\n <br>\n _Default_: `1`\n\n- **`max_items`**\n <br>\n Maximum number of suggestions to display.\n <br>\n _Default_: `10`\n\n- **`autofirst`**\n <br>\n Should the first element be automatically selected?\n <br>\n _Default_: `True`\n\n## AwesompleteTagsWidgetWrapper\n\nThis widget is a subclass of the `AwesompleteWidgetWrapper` and intended to be used\nfor entering comma-separated values.\n\nThis widget can be used with [django-taggit](https://github.com/jazzband/django-taggit)\n\n```python\nfrom django import forms\nfrom awesomplete.widgets import AwesompleteTagsWidgetWrapper\nfrom taggit.models import Tag\nfrom taggit.forms import TagWidget\nfrom .models import City\n\n\ndef get_tag_suggestions():\n return Tag.objects.values_list(\n 'name',\n flat=True\n ).order_by('name').distinct()\n\n\nclass CityForm(forms.ModelForm):\n class Meta:\n model = City\n fields = forms.ALL_FIELDS\n widgets = {\n 'tags': AwesompleteTagsWidgetWrapper(\n widget=TagWidget,\n suggestions=get_tag_suggestions\n )\n }\n\n```\n\n\n\n## Links\n\n- [awesomplete](http://leaverou.github.io/awesomplete/) created by Lea Verou.\n\n## License\n\nCopyright (c) 2018 Mihail Mishakin Released under the BSD license (see LICENSE)\n",
"bugtrack_url": null,
"license": "BSD license",
"summary": "A django app that provides suggestions while you type into the field.",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/dldevinc/django-awesomplete"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db4370f3509f35529a5f495f1fbd6c3ea849b911f189a4773fbe9e3c6f022a59",
"md5": "f010d64b9d2a73cc194b367791807e8e",
"sha256": "fb6884deeff964041b0f2650eef383378db9aacc42a666112953925725241502"
},
"downloads": -1,
"filename": "django_awesomplete-0.6.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f010d64b9d2a73cc194b367791807e8e",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 25590,
"upload_time": "2024-02-12T09:44:59",
"upload_time_iso_8601": "2024-02-12T09:44:59.712354Z",
"url": "https://files.pythonhosted.org/packages/db/43/70f3509f35529a5f495f1fbd6c3ea849b911f189a4773fbe9e3c6f022a59/django_awesomplete-0.6.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "333924c991b3138e4d7d70f61081d0451d5dfcc1b3106c125f74e54de5a851a6",
"md5": "8eaac5ce124e0472018b25ad54c8cf50",
"sha256": "d4df7e470593846f91e1d14f20edc2f24476782d35ff7075714a0afe08fabdb2"
},
"downloads": -1,
"filename": "django-awesomplete-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "8eaac5ce124e0472018b25ad54c8cf50",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 26064,
"upload_time": "2024-02-12T09:45:00",
"upload_time_iso_8601": "2024-02-12T09:45:00.999270Z",
"url": "https://files.pythonhosted.org/packages/33/39/24c991b3138e4d7d70f61081d0451d5dfcc1b3106c125f74e54de5a851a6/django-awesomplete-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 09:45:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dldevinc",
"github_project": "django-awesomplete",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "django-taggit",
"specs": []
},
{
"name": "pytest",
"specs": [
[
"==",
"7.0.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.4.4"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"4.0.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"4.1.0"
]
]
},
{
"name": "pytest-django",
"specs": [
[
"==",
"4.5.2"
]
]
},
{
"name": "pytest-django",
"specs": [
[
"==",
"4.8.0"
]
]
},
{
"name": "pytest-xdist",
"specs": [
[
"==",
"3.0.2"
]
]
},
{
"name": "pytest-xdist",
"specs": [
[
"==",
"3.5.0"
]
]
}
],
"tox": true,
"lcname": "django-awesomplete"
}
JSON
