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.
- 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, inherit from autocomplete_light.ModelForm and remove calls to get_widgets_dict. Optionnaly remove all old widget definitions.
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 package with pip
- Append 'autocomplete_light' to settings.INSTALLED_APPS
- Call autocomplete_light.autodiscover() before admin.autodiscover()
- Include autocomplete_light.urls
- Ensure understanding of django.contrib.staticfiles
- Include autocomplete_light/static.html after loading jquery.js (>=1.7)
- Optionaly include it in admin/base_site.html too
If you didn’t click any, and this is your first install: bravo !
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.
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
- Working around Django bug #9321: Hold down “Control” ...
- Override a default relation select in ModelForm.Meta.widgets
- Or in a ModelChoiceField or similar
- Using your own form in a ModelAdmin
- Using autocomplete widgets in non model-forms
- Overriding a JS option in Python
- Using $.yourlabsAutocomplete to create a navigation autocomplete
- Using the choiceSelector option to enable keyboard navigation
- Using the selectChoice event 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
You should now fully understand the concepts and be able to do literally what you want.
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
Integration with external apps¶
Python API reference¶
- import autocomplete_light
- Form shortcuts