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.
Features¶
Features include:
- 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 ...
- 100% overridable HTML, CSS, Python and Javascript: there is no variable hidden far down in the scope anywhere.
- 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.
Resources¶
Resources include:
Demo¶
You can run test projects for a local demo in a temporary virtualenv.
Install¶
Click on any instruction step for details.
- Install the
django-autocomplete-lightpackage with pip - Append
'autocomplete_light'tosettings.INSTALLED_APPS - Call
autocomplete_light.autodiscover()beforeadmin.autodiscover() - Include
autocomplete_light.urls - Ensure understanding of
django.contrib.staticfiles - Include
autocomplete_light/static.htmlafter loading jquery.js (>=1.7) - Optionaly include it in
admin/base_site.htmltoo
If you didn’t click any, and this is your first install: bravo !
Upgrade¶
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.
Tutorial¶
Learn the concepts by doing useful things.
- Enable an autocomplete in admin forms in two steps: high level API concepts
- Making Autocomplete classes
- Your own form classes
- Javascript API concepts
- Using
$.yourlabsAutocompleteto create a navigation autocomplete - Using the
choiceSelectoroption to enable keyboard navigation - Using the
selectChoiceevent to enable keyboard choice selection - Combining the above to make a navigation autocomplete for mouse and keyboard
- Override autocomplete JS options in JS
- Override autocomplete JS methods
- Overload autocomplete JS methods
- Get an existing autocomplete object and chain autocompletes
- Overriding widget JS methods
- Using
You should now fully understand the concepts and be able to do literally what you want.
Topics¶
Using just the concepts you’ve learned in the tutorial, we’ve built-in several really cool things, backed by live examples.
- Templating autocompletes
- Making a global navigation autocomplete
- CharField autocompletes
- AutocompleteGeneric, for GenericForeignKey or GenericManyToMany
- Dependencies between autocompletes
- Add another popup outside the admin
- Proposing results from a remote API
- Django 1.3 support workarounds
- When things go wrong
- Voodoo black magic