1- .. Django-Select2 documentation master file, created by
2- sphinx-quickstart on Sat Aug 25 10:23:46 2012.
3- You can adapt this file completely to your liking, but it should at least
4- contain the root `toctree` directive.
1+ .. include :: ../README.rst
2+
3+ Installation
4+ ------------
5+
6+ Install ``django-select2 ``
7+
8+ .. code-block :: python
9+
10+ python3 - m pip install django- select2
11+
12+ django_select2 `` to your ``INSTALLED_APPS `` in your project settings.
13+
14+ Add ``django_select `` to your URL root configuration:
15+
16+ .. code-block :: python
17+
18+ from django.urls import include, path
19+
20+ urlpatterns = [
21+ # … other patterns
22+ path(" select2/" " django_select2.urls"
23+ # … other patterns
24+ ]
25+
26+
27+ :class: `.DummyCache ` or :class: `.LocMemCache `), we will use Redis in this
28+ example. Make sure you have a Redis server up and running::
29+
30+ # Debian
31+ sudo apt-get install redis-server
32+
33+ # macOS
34+ brew install redis
35+
36+ # install Redis python client
37+ python3 -m pip install django-redis
38+
39+ Next, add the cache configuration to your ``settings.py `` as follows:
40+
41+ .. code-block :: python
42+
43+ CACHES = {
44+ # … default cache config and others
45+ " select2"
46+ " BACKEND" " django_redis.cache.RedisCache"
47+ " LOCATION" " redis://127.0.0.1:6379/2"
48+ " OPTIONS"
49+ " CLIENT_CLASS" " django_redis.client.DefaultClient"
50+ }
51+ }
52+ }
53+
54+ # Tell select2 which cache configuration to use:
55+ SELECT2_CACHE_BACKEND = " select2"
56+
57+
58+
59+ ---------------------
60+
61+ - jQuery is not included in the package since it is
62+ expected that in most scenarios this would already be available.
63+
64+
65+ Quick Start
66+ -----------
67+
68+ Here is a quick example to get you started:
69+
70+ First make sure you followed the installation instructions above.
71+ Once everything is setup, let's start with a simple example.
72+
73+ We have the following model:
74+
75+ .. code-block :: python
76+
77+ # models.py
78+ from django.conf import settings
79+ from django.db import models
80+
81+
82+ class Book (models .Model ):
83+ author = models.ForeignKey(settings.AUTH_USER_MODEL , on_delete = models.CASCADE )
84+ co_authors = models.ManyToManyField(settings.AUTH_USER_MODEL , related_name = ' co_authored_by'
85+
86+
87+
88+
89+ .. code-block :: python
90+
91+ # forms.py
92+ from django import forms
93+ from django_select2 import forms as s2forms
94+
95+ from . import models
96+
97+
98+ class AuthorWidget (s2forms .ModelSelect2Widget ):
99+ search_fields = [
100+ " username__icontains"
101+ " email__icontains"
102+ ]
103+
104+
105+ class CoAuthorsWidget (s2forms .ModelSelect2MultipleWidget ):
106+ search_fields = [
107+ " username__icontains"
108+ " email__icontains"
109+ ]
110+
111+
112+ class BookForm (forms .ModelForm ):
113+ class Meta :
114+ model = models.Book
115+ fields = " __all__"
116+ widgets = {
117+ " author"
118+ " co_authors"
119+ }
120+
121+
122+
123+ .. code-block :: python
124+
125+ # views.py
126+ from django.views import generic
127+
128+ from . import forms, models
129+
130+
131+ class BookCreateView (generic .CreateView ):
132+ model = models.Book
133+ form_class = forms.BookForm
134+ success_url = " /"
135+
136+ urls.py ``:
137+
138+ .. code-block :: python
139+
140+ # urls.py
141+ from django.urls import include, path
142+
143+ from . import views
144+
145+ urlpatterns = [
146+ # … other patterns
147+ path(" select2/" " django_select2.urls"
148+ # … other patterns
149+ path(" book/create" name = " book-create"
150+ ]
151+
152+
153+ myapp/templates/myapp/book_form.html ``
154+
155+ .. code-block :: HTML
156+
157+ <!DOCTYPE html>
158+ <html lang =" en"
159+ <head >
160+ <title >Create Book</title >
161+ {{ form.media.css }}
162+ <style >
163+ input , select {width 100% }
164+ </style >
165+ </head >
166+ <body >
167+ <h1 >Create a new Book</h1 >
168+ <form method =" POST"
169+ {% csrf_token %}
170+ {{ form.as_p }}
171+ <input type =" submit"
172+ </form >
173+ <script src =" https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.min.js" script >
174+ {{ form.media.js }}
175+ </body >
176+ </html >
177+
178+ Done - enjoy the wonders of Select2!
179+
180+
181+ Changelog
182+ ---------
183+
184+ See `Github releases `_.
185+
186+ .. _Github releases : https://github.com/applegrew/django-select2/releases
5187
6188All Contents
7189============
@@ -12,7 +194,6 @@ Contents:
12194 :maxdepth: 2
13195 :glob:
14196
15- get_started
16197 django_select2
17198 extra
18199 CONTRIBUTING
0 commit comments