This is a Django integration of Select2.
The app includes Select2 driven Django Widgets and Form Fields.
These components are responsible for rendering the necessary Javascript and HTML markups. Since this whole package is to render choices using Select2 Javascript library, hence these components are meant to be used with choice fields.
Widgets are generally of two types :-
1. Light – They are not meant to be used when there are too many options, say, in thousands. This is because all those options would have to be pre-rendered onto the page and Javascript would be used to search through them. Said that, they are also one the most easiest to use. They are almost drop-in-replacement for Django’s default select widgets.
2. Heavy – They are suited for scenarios when the number of options are large and need complex queries (from maybe different sources) to get the options. This dynamic fetching of options undoubtably requires Ajax communication with the server. Django-Select2 includes a helper JS file which is included automatically, so you need not worry about writing any Ajax related JS code. Although on the server side you do need to create a view specifically to respond to the queries.
Heavies have further specialized versions called – Auto Heavy. These do not require views to server Ajax request. When they are instantiated, they register themselves with one central view which handels Ajax requests for them.
Heavy widgets have the word ‘Heavy’ in their name. Light widgets are normally named, i.e. there is no ‘Light’ word in their names.
Available widgets:
Select2Widget, Select2MultipleWidget, HeavySelect2Widget, HeavySelect2MultipleWidget, AutoHeavySelect2Widget, AutoHeavySelect2MultipleWidget
These are pre-implemented choice fields which use the above widgets. It is highly recommended that you use them instead of rolling your own.
The fields available are good for general purpose use, although more specialized versions too are available for your ease.
Available fields:
Select2ChoiceField, Select2MultipleChoiceField, HeavySelect2ChoiceField, HeavySelect2MultipleChoiceField, HeavyModelSelect2ChoiceField, HeavyModelSelect2MultipleChoiceField, ModelSelect2Field, ModelSelect2MultipleField, AutoSelect2Field, AutoSelect2MultipleField, AutoModelSelect2Field, AutoModelSelect2MultipleField
The view - Select2View, exposed here is meant to be used with ‘Heavy’ fields and widgets.
Imported:
Install django_select2:
pip install django_select2
Add django_select2 to your INSTALLED_APPS in your project settings.
When deploying on production server, run:
python manage.py collectstatic
AUTO_RENDER_SELECT2_STATICS [Default True]
This, when specified and set to False in settings.py then Django_Select2 widgets won’t automatically include the required scripts and stylesheets. When this setting is True then every Select2 field on the page will output <script> and <link> tags to include the required JS and CSS files. This is convinient but will output the same JS and CSS files multiple times if there are more than one Select2 fields on the page.
When this settings is False then you are responsible for including the JS and CSS files. To help you with this the following template tags are available in django_select2_tags.
- import_django_select2_js - Outputs <script> tags to include all the JS files, required by Light and Heavy widgets.
- import_django_select2_css - Outputs <link> tags to include all the CSS files, required by Light and Heavy widgets.
- import_django_select2_js_css - Outputs both <script> and <link> tags to include all the JS and CSS files, required by Light and Heavy widgets.
Make sure to include them at the top of the page, prefereably in <head>...</head>.
Please see testapp application. This application is used to manually test the functionalities of this package. This also serves as a good example.
You need only Django 1.4 or above to run that. It might run on older versions but that is not tested.