Welcome to django-autocomplete-light’s documentation!¶
django-autocomplete-light’s purpose is to enable autocompletes quickly and properly in a django project: it is the fruit of years of R&D. It was designed for Django so that every part overridable or reusable independently. It is stable, tested, documented and fully supported: it tries to be a good neighbour in Django ecosystem.
- WARNING you are currently on the v2 branch where new development happens.
- master (v1) is still supported for BC.
- charfield, foreign key, many to many autocomplete widgets,
- generic foreign key, generic many to many autocomplete widgets,
- remote API backed-autocompletes,
- django template engine support for autocompletes, enabling you to include images etc ...
- add-another popup supported outside the admin too.
- keyboard is supported with enter, tab and arrows by default.
Each feature has a live example and is fully documented. It is also designed and documented so that you create your own awesome features too.
v2 branch is under active development. You might want to use that instead, since it’s much easier to work with and supports python3.
In this case, please refer to the v2 documentation.
To upgrade to v2, please enjoy the v1 to v2 upgrade instructions (documented with love !).
- the Autocomplete class design hasn’t changed at all.
- yourlabsWidget() doesn’t parses data-* options the same,
- the django/form python code has been re-organised ie. get_widgets_dict() is gone and autocomplete_light.ModelForm wraps around all features.
You can run test projects for a local demo in a temporary virtualenv.
Click on any instruction step for details.
- Install the django-autocomplete-light>=2.0.0pre package with pip
- Append 'autocomplete_light' to settings.INSTALLED_APPS before django.contrib.admin
- If using Django < 1.7, call autocomplete_light.autodiscover() before admin.autodiscover()
- Include autocomplete_light.urls
- Ensure you understand django.contrib.staticfiles
- Include autocomplete_light/static.html after loading jquery.js (>=1.7)
- Optionally include it in admin/base_site.html too
If you didn’t click any, and this is your first install: bravo !
v1 to v2¶
- Upgrading from django-autocomplete-light v1 to v2
- You should not use widget directly anymore
- Specification of the Autocomplete class to use
- Python class re-organisation
- Deprecation of autocomplete_js_attributes and widget_js_attributes
- max-values was renamed to maximum-values
- data-autocomplete-placeholder is gone in favor of HTML5 placeholder attribute
- Widget template changes
- Script changes
Run pip install -U django-autocomplete-light. Check the CHANGELOG for BC (Backward Compatibility) breaks. There should be none for minor version upgrades ie. from 1.1.3 to 1.1.22, but there might be some minor BC breaks for middle upgrades ie. 1.2.0 to 1.3.0.
Enabling autocompletes inside and outside of the admin has become piece of cake.
If you need anything more than just enabling autocompletes in the admin, then you should understand django-autocomplete-light’s architecture. Because you can override any part of it.
The architecture is based on 3 main parts which you can override to build insanely creative features as many users already did.
- Autocomplete classes
- Design documentation
- Form, fields and widgets
- Design documentation
- Voodoo black magic
Using just the concepts you’ve learned in the reference, here are some of the things you can do.
- How to run tests
- Why not use Widget.Media ?
- Model field’s help_text and verbose_name are lost when overriding the widget
- Fields bound on values which are not in the queryset anymore raise a ValidationError
- How to override a JS method ?
- How to work around Django bug #9321: Hold down “Control” ... ?
- How to report a bug effectively ?
- How to ask for help ?