<h1>Using Django Admin Sortable<aclass="headerlink"href="#using-django-admin-sortable"title="Permalink to this headline">¶</a></h1>
<divclass="section"id="models">
<h2>Models<aclass="headerlink"href="#models"title="Permalink to this headline">¶</a></h2>
<p>To add sorting to a model, your model needs to inherit from <codeclass="docutils literal"><spanclass="pre">Sortable</span></code> and have an inner <codeclass="docutils literal"><spanclass="pre">Meta</span></code> class that inherits from <codeclass="docutils literal"><spanclass="pre">Sortable.Meta</span></code>:</p>
<p>It is also possible to order objects relative to another object that is a ForeignKey.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">A small caveat here is that <codeclass="docutils literal"><spanclass="pre">Category</span></code> must also either inherit from <codeclass="docutils literal"><spanclass="pre">Sortable</span></code> or include an <codeclass="docutils literal"><spanclass="pre">order</span></code> property which is a <codeclass="docutils literal"><spanclass="pre">PositiveSmallInteger</span></code> field. This is due to the way Django admin instantiates classes.</p>
</div>
<p><codeclass="docutils literal"><spanclass="pre">Sortable</span></code> has one field: <codeclass="docutils literal"><spanclass="pre">order</span></code> and adds a default ordering value set to <codeclass="docutils literal"><spanclass="pre">order</span></code>, ascending.</p>
<h3>Adding Sortable to an existing model<aclass="headerlink"href="#adding-sortable-to-an-existing-model"title="Permalink to this headline">¶</a></h3>
<p>If you’re adding Sorting to an existing model, it is recommended that you use <aclass="reference external"href="http://south.areacode.com/">django-south</a> to create a schema migration to add the “order” field to your model. You will also need to create a data migration in order to add the appropriate values for the <codeclass="docutils literal"><spanclass="pre">order</span></code> column.</p>
<p>Example assuming a model named “Category”:</p>
<p>See <aclass="reference external"href="http://south.readthedocs.org/en/latest/tutorial/part3.html">this link</a> for more information on Data Migrations.</p>
"""Your generic inline options go here"""
</pre></div>
</div>
<divclass="section"id="overriding-queryset">
<h3>Overriding <codeclass="docutils literal"><spanclass="pre">queryset()</span></code><aclass="headerlink"href="#overriding-queryset"title="Permalink to this headline">¶</a></h3>
<p>django-admin-sortable supports custom queryset overrides on admin models and inline models in Django admin!</p>
<p>If you’re providing an override of a <codeclass="docutils literal"><spanclass="pre">SortableAdmin</span></code> or <codeclass="docutils literal"><spanclass="pre">Sortable</span></code> inline model, you don’t need to do anything extra. django-admin-sortable will automatically honor your queryset.</p>
<p>Have a look at the <codeclass="docutils literal"><spanclass="pre">WidgetAdmin</span></code> class in the sample project for an example of an admin class with a custom <codeclass="docutils literal"><spanclass="pre">queryset()</span></code> override.</p>
<h3>Overriding <codeclass="docutils literal"><spanclass="pre">queryset()</span></code> for an inline model<aclass="headerlink"href="#overriding-queryset-for-an-inline-model"title="Permalink to this headline">¶</a></h3>
<p>This is a special case, which requires a few lines of extra code to properly determine the sortability of your model. Example:</p>
<divclass="highlight-python"><divclass="highlight"><pre><spanclass="c"># add this import to your admin.py</span>
<p>If you override the queryset of an inline, the number of objects present may change, and adminsortable won’t be able to automatically determine if the inline model is sortable from here, which is why we have to set the <codeclass="docutils literal"><spanclass="pre">is_sortable</span></code> property of the model in this method.</p>
<h3>Sorting subsets of objects<aclass="headerlink"href="#sorting-subsets-of-objects"title="Permalink to this headline">¶</a></h3>
<p>It is also possible to sort a subset of objects in your model by adding a <codeclass="docutils literal"><spanclass="pre">sorting_filters</span></code> tuple. This works exactly the same as <codeclass="docutils literal"><spanclass="pre">.filter()</span></code> on a QuerySet, and is applied <em>after</em><codeclass="docutils literal"><spanclass="pre">get_queryset()</span></code> on the admin class, allowing you to override the queryset as you would normally in admin but apply additional filters for sorting. The text “Change Order of” will appear before each filter in the Change List template, and the filter groups are displayed from left to right in the order listed. If no <codeclass="docutils literal"><spanclass="pre">sorting_filters</span></code> are specified, the text “Change Order” will be displayed for the link.</p>
<p>An example of sorting subsets would be a “Board of Directors”. In this use case, you have a list of “People” objects. Some of these people are on the Board of Directors and some not, and you need to sort them independently:</p>
<pclass="last">django-admin-sortable 1.6.6 introduces a backwards-incompatible change for <codeclass="docutils literal"><spanclass="pre">sorting_filters</span></code>. Previously this attribute was defined as a dictionary, so you’ll need to change your values over to the new tuple-based format.</p>
<h3>Extending custom templates<aclass="headerlink"href="#extending-custom-templates"title="Permalink to this headline">¶</a></h3>
<p>By default, adminsortable’s change form and change list views inherit from Django admin’s standard templates. Sometimes you need to have a custom change form or change list, but also need adminsortable’s CSS and JavaScript for inline models that are sortable for example.</p>
<p><codeclass="docutils literal"><spanclass="pre">SortableAdmin</span></code> has two attributes you can override for this use case:</p>
<p>If you need to extend the inline change form templates, you’ll need to select the right one, depending on your version of Django. For Django 1.5.x or below, you’ll need to extend one of the following:</p>
<pclass="last">A Special Note About Stacked Inlines...
The height of a stacked inline model can dynamically increase, which can make them difficult to sort. If you anticipate the height of a stacked inline is going to be very tall, I would suggest using TabularStackedInline instead.</p>
