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 half a decade of R&D and thousands of contributions. 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.
Projects upgrading to Django 1.9¶
DAL has been ready for Django 1.9 since April 2015 thanks to @blueyed & @jpic. HOWEVER due to the app loading refactor in 1.9 you should apply the following:
find . -name '*.py' | xargs perl -i -pe 's/import autocomplete_light/from autocomplete_light import shortcuts as autocomplete_light/'
See the test_project running on Django 1.9 and its new cool admin theme: http://dal-yourlabs.rhcloud.com/admin (test:test).
- charfield, foreign key, many to many autocomplete widgets,
- generic foreign key, generic many to many autocomplete widgets,
- 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.
- Django 1.7 to 1.10, PyPy, Python 2 and 3, PostgreSQL, SQLite, MySQL
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.
- **Documentation** graciously hosted by RTFD
- Live demo graciously hosted by RedHat, thanks to PythonAnywhere for hosting it in the past,
- Video demo graciously hosted by Youtube,
- Mailing list graciously hosted by Google
- Git graciously hosted by GitHub,
- Package graciously hosted by PyPi,
- Continuous integration graciously hosted by Travis-ci
- **Online paid support** provided via HackHands,
While you can use the live demo hosted by RedHat on OpenShift, you can run test projects for a local demo in a temporary virtualenv.
Advanced Django users are likely to install it in no time by following this step-list. Click on a step for details.
- Install the
django-autocomplete-light>=2.0.0prepackage with pip
- Django < 1.7 support: call
- Ensure you understand
autocomplete_light/static.htmlafter loading jquery.js (>=1.7)
- Optionally include it in
If you didn’t click any, and this is your first install: bravo !
Enabling autocompletes inside and outside of the admin has become piece of cake.
Reference and design documentation¶
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.
Using just the concepts you’ve learned in the reference, here are some of the things you can do.
- Can’t see admin add-another
+button when overriding a
- RemovedInDjango18Warning: Creating a ModelForm without either the ‘fields’ attribute or the ‘exclude’ attribute is deprecated - form YourForm needs updating
- How to run tests
- Why not use Widget.Media ?
- Model field’s
verbose_nameare 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 ?
Any change is documented in the Change log for django-autocomplete-light, so upgrading from a version
to another is always documented there. Usualy, upgrade from pip with a command
pip install -U django-autocomplete-light. Check the CHANGELOG for BC
(Backward Compatibility) breaks. There should is no backward compatibility 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.