<h1>Get Started<aclass="headerlink"href="#get-started"title="Permalink to this headline">¶</a></h1>
<divclass="section"id="module-django_select2">
<spanid="overview"></span><h2>Overview<aclass="headerlink"href="#module-django_select2"title="Permalink to this headline">¶</a></h2>
<p>This is a <aclass="reference external"href="https://www.djangoproject.com/">Django</a> integration of <aclass="reference external"href="http://ivaynberg.github.com/select2/">Select2</a>.</p>
<p>The app includes Select2 driven Django Widgets and Form Fields.</p>
<divclass="section"id="widgets">
<h3>Widgets<aclass="headerlink"href="#widgets"title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>Widgets are generally of two types :-</p>
<blockquote>
<div><p>1. <strong>Light</strong>–
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.</p>
<p>2. <strong>Heavy</strong>–
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.</p>
<p>Heavies have further specialized versions called –<strong>Auto Heavy</strong>. 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.</p>
</div></blockquote>
<p>Heavy widgets have the word ‘Heavy’ in their name. Light widgets are normally named, i.e. there is no ‘Light’ word
<p>This, when specified and set to <ttclass="docutils literal"><spanclass="pre">False</span></tt> in <ttclass="docutils literal"><spanclass="pre">settings.py</span></tt> then Django_Select2 widgets won’t automatically include the required scripts and stylesheets. When this setting is <ttclass="docutils literal"><spanclass="pre">True</span></tt> then every Select2 field on the page will output <ttclass="docutils literal"><spanclass="pre"><script></span></tt> and <ttclass="docutils literal"><spanclass="pre"><link></span></tt> 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.</p>
<p>When this settings is <ttclass="docutils literal"><spanclass="pre">False</span></tt> then you are responsible for including the JS and CSS files. To help you with this the following template tags are available in <ttclass="docutils literal"><spanclass="pre">django_select2_tags</span></tt>.</p>
<blockquote>
<div><ulclass="simple">
<li><ttclass="docutils literal"><spanclass="pre">import_django_select2_js</span></tt> - Outputs <ttclass="docutils literal"><spanclass="pre"><script></span></tt> tags to include all the JS files, required by Light and Heavy widgets.</li>
<li><ttclass="docutils literal"><spanclass="pre">import_django_select2_css</span></tt> - Outputs <ttclass="docutils literal"><spanclass="pre"><link></span></tt> tags to include all the CSS files, required by Light and Heavy widgets.</li>
<li><ttclass="docutils literal"><spanclass="pre">import_django_select2_js_css</span></tt> - Outputs both <ttclass="docutils literal"><spanclass="pre"><script></span></tt> and <ttclass="docutils literal"><spanclass="pre"><link></span></tt> tags to include all the JS and CSS files, required by Light and Heavy widgets.</li>
</ul>
</div></blockquote>
<p>Make sure to include them at the top of the page, prefereably in <ttclass="docutils literal"><spanclass="pre"><head>...</head></span></tt>.</p>
</div>
<divclass="section"id="external-dependencies">
<h2>External Dependencies<aclass="headerlink"href="#external-dependencies"title="Permalink to this headline">¶</a></h2>
<ulclass="simple">
<li>Django - This is obvious.</li>
<li>jQuery - This is not included in the package since it is expected that in most scenarios this would already be available. The above template tags also won’t out <ttclass="docutils literal"><spanclass="pre"><script></span></tt> tag to include this. You need to do this yourself.</li>
</ul>
</div>
<divclass="section"id="example-application">
<h2>Example Application<aclass="headerlink"href="#example-application"title="Permalink to this headline">¶</a></h2>
<p>Please see <ttclass="docutils literal"><spanclass="pre">testapp</span></tt> application. This application is used to manually test the functionalities of this package. This also serves as a good example.</p>
<p>You need only Django 1.4 or above to run that. It might run on older versions but that is not tested.</p>
</div>
</div>
</div>
</div>
</div>
<divclass="sphinxsidebar">
<divclass="sphinxsidebarwrapper">
<h3><ahref="index.html">Table Of Contents</a></h3>
