Added usage docs.

docs/_build/html/_sources/usage.txt

@@ -0,0 +1,167 @@
+Using Django Admin Sortable
+===========================
+
+Models
+------
+
+To add sorting to a model, your model needs to inherit from ``Sortable`` and have an inner ``Meta`` class that inherits from ``Sortable.Meta``::
+
+    # models.py
+    from adminsortable.models import Sortable
+
+    class MySortableClass(Sortable):
+        class Meta(Sortable.Meta):
+            pass
+
+        title = models.CharField(max_length=50)
+
+        def __unicode__(self):
+            return self.title
+
+It is also possible to order objects relative to another object that is a ForeignKey.
+
+.. note:: A small caveat here is that ``Category`` must also either inherit from ``Sortable`` or include an ``order`` property which is a ``PositiveSmallInteger`` field. This is due to the way Django admin instantiates classes.
+
+``Sortable`` has one field: ``order`` and adds a default ordering value set to ``order``, ascending.
+
+Adding Sortable to an existing model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you're adding Sorting to an existing model, it is recommended that you use `django-south <http://south.areacode.com/>`_ 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 ``order`` column.
+
+Example assuming a model named "Category"::
+
+    def forwards(self, orm):
+        for index, category in enumerate(orm.Category.objects.all()):
+            category.order = index + 1
+            category.save()
+
+See `this link <http://south.readthedocs.org/en/latest/tutorial/part3.html>`_ for more information on Data Migrations.
+
+Django Admin Integration
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To enable sorting in the admin, you need to inherit from ``SortableAdmin``::
+
+        from django.contrib import admin
+        from myapp.models import MySortableClass
+        from adminsortable.admin import SortableAdmin
+
+        class MySortableAdminClass(SortableAdmin):
+            """Any admin options you need go here"""
+
+        admin.site.register(MySortableClass, MySortableAdminClass)
+
+To enable sorting on TabularInline models, you need to inherit from SortableTabularInline::
+
+    from adminsortable.admin import SortableTabularInline
+
+    class MySortableTabularInline(SortableTabularInline):
+        """Your inline options go here"""
+
+To enable sorting on StackedInline models, you need to inherit from SortableStackedInline::
+
+    from adminsortable.admin import SortableStackedInline
+
+    class MySortableStackedInline(SortableStackedInline):
+        """Your inline options go here"""
+
+There are also generic equivalents that you can inherit from::
+
+    from adminsortable.admin import (SortableGenericTabularInline,
+        SortableGenericStackedInline)
+        """Your generic inline options go here"""
+
+Overriding ``queryset()``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+django-admin-sortable supports custom queryset overrides on admin models and inline models in Django admin!
+
+If you're providing an override of a ``SortableAdmin`` or ``Sortable`` inline model, you don't need to do anything extra. django-admin-sortable will automatically honor your queryset.
+
+Have a look at the ``WidgetAdmin`` class in the sample project for an example of an admin class with a custom ``queryset()`` override.
+
+Overriding ``queryset()`` for an inline model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is a special case, which requires a few lines of extra code to properly determine the sortability of your model. Example::
+
+    # add this import to your admin.py
+    from adminsortable.utils import get_is_sortable
+
+
+    class ComponentInline(SortableStackedInline):
+        model = Component
+
+        def queryset(self, request):
+            qs = super(ComponentInline, self).queryset(request).filter(
+                title__icontains='foo')
+
+            # You'll need to add these lines to determine if your model
+            # is sortable once we hit the change_form() for the parent model.
+
+            if get_is_sortable(qs):
+                self.model.is_sortable = True
+            else:
+                self.model.is_sortable = False
+            return qs
+
+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 ``is_sortable`` property of the model in this method.
+
+Sorting subsets of objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is also possible to sort a subset of objects in your model by adding a ``sorting_filters`` tuple. This works exactly the same as ``.filter()`` on a QuerySet, and is applied *after* ``get_queryset()`` 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 ``sorting_filters`` are specified, the text "Change Order" will be displayed for the link.
+
+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::
+
+    class Person(Sortable):
+        class Meta(Sortable.Meta):
+            verbose_name_plural = 'People'
+
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+        is_board_member = models.BooleanField('Board Member', default=False)
+
+        sorting_filters = (
+            ('Board Members', {'is_board_member': True}),
+            ('Non-Board Members', {'is_board_member': False}),
+        )
+
+        def __unicode__(self):
+            return '{} {}'.format(self.first_name, self.last_name)
+
+
+.. warning::
+
+    django-admin-sortable 1.6.6 introduces a backwards-incompatible change for ``sorting_filters``. Previously this attribute was defined as a dictionary, so you'll need to change your values over to the new tuple-based format.
+
+Extending custom templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+``SortableAdmin`` has two attributes you can override for this use case::
+
+    change_form_template_extends
+    change_list_template_extends
+
+These attributes have default values of::
+
+    change_form_template_extends = 'admin/change_form.html'
+    change_list_template_extends = 'admin/change_list.html'
+
+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::
+
+    templates/adminsortable/edit_inline/stacked-1.5.x.html
+    templates/adminsortable/edit_inline/tabular-inline-1.5.x.html
+
+For Django >= 1.6.x, extend::
+
+    templates/adminsortable/edit_inline/stacked.html
+    templates/adminsortable/edit_inline/tabular.html
+
+.. note::
+
+    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.

docs/_build/html/genindex.html

@@ -64,6 +64,10 @@
 <li class="toctree-l2"><a class="reference internal" href="configuration.html#static-media">Static Media</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">Using Django Admin Sortable</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="usage.html#models">Models</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
 </ul>
 

docs/_build/html/index.html

@@ -64,6 +64,10 @@
 <li class="toctree-l2"><a class="reference internal" href="configuration.html#static-media">Static Media</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">Using Django Admin Sortable</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="usage.html#models">Models</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
 </ul>
 
@@ -136,6 +140,10 @@
 <li class="toctree-l2"><a class="reference internal" href="configuration.html#static-media">Static Media</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">Using Django Admin Sortable</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="usage.html#models">Models</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
 </ul>
 </div>

docs/_build/html/search.html

@@ -63,6 +63,10 @@
 <li class="toctree-l2"><a class="reference internal" href="configuration.html#static-media">Static Media</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">Using Django Admin Sortable</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="usage.html#models">Models</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
 </ul>
 

docs/_build/html/searchindex.js

@@ -1 +1 @@
-Search.setIndex({envversion:42,terms:{through:0,file:[1,2],group:0,thank:0,easi:0,should:3,add:[0,1,3],folder:1,adminsort:[1,3],modul:0,introduc:0,"return":3,get:[1,3],python:[0,2],context_processor:[1,3],"import":3,now:3,tbd:[],template_context_processor:[1,3],enabl:0,drop:[0,2,3],staticfil:1,item:0,found:2,where:[2,3],page:0,view:[2,3],pleas:0,set:3,sortableadmin:3,individu:0,see:2,meta:3,"static":3,pass:3,click:2,compat:0,index:0,wire:3,defin:3,content:[],"new":[],method:1,attribut:0,altern:1,core:[1,3],run:2,insid:1,javascript:1,here:3,base:0,symlink:1,locat:1,"super":0,"__unicode__":3,search:0,manag:[0,2],charfield:3,chang:[0,2],via:2,simpli:3,directli:2,extra:3,app:[1,2],prefer:1,ensur:[1,3],instal:3,installed_app:[1,3],your:[0,1,3],unit:2,quit:1,from:[1,2,3],wai:0,area:2,regist:3,custom:2,start:3,max_length:3,includ:[1,2],taken:2,more:3,"function":2,desir:3,option:3,form:2,tupl:0,tool:[2,3],copi:1,ani:[0,2,3],link:[2,3],entequak:0,inlin:[0,2],present:3,serv:1,made:0,look:2,work:2,project:[1,2,3],record:2,below:0,can:[1,2,3],def:3,sai:2,quickstart:[],few:1,almost:0,changelist:3,site:3,need:3,have:[2,3],pip:3,mysortableadminclass:3,incompat:0,mysortableclass:3,titl:3,self:3,format:0,when:[2,3],also:0,take:3,test:[],you:[0,1,2,3],simpl:1,css:1,updat:0,sorting_filt:0,"class":3,object:3,drag:[0,2,3],mai:[0,2],login:2,directori:[1,2],credenti:2,inherit:3,sample_project:2,thi:2,model:[0,2,3],backward:0,order:[0,2,3],latest:0},objtypes:{},objnames:{},filenames:["index","configuration","testing","quickstart"],titles:["Welcome to Django Admin Sortable’s documentation!","Configuring Django Admin Sortable","Testing","Quickstart"],objects:{},titleterms:{what:0,sortabl:[0,1],welcom:0,quickstart:3,admin:[0,1],media:1,support:0,configur:1,indic:0,django:[0,1],content:0,version:0,"static":1,tabl:0,test:2,"new":0,document:0,higher:[]}})
+Search.setIndex({envversion:42,terms:{serv:2,all:0,code:0,anticip:0,text:0,over:0,veri:0,through:1,file:[2,3],follow:0,entequak:1,dynam:0,previous:0,categori:0,componentinlin:0,group:[0,1],thank:1,easi:1,field:0,should:4,add:[0,1,2,4],title__icontain:0,board:0,onc:0,els:0,folder:2,save:0,adminsort:[0,2,4],app:[2,3],introduc:[0,1],custom:3,them:0,"return":[0,4],get:[2,4],python:[1,3],util:0,context_processor:[2,4],is_board_memb:0,"import":[0,4],increas:0,now:4,is_sort:0,tbd:[],requir:0,template_context_processor:[2,4],enabl:[0,1],anyth:0,drop:[1,3,4],list:0,last_nam:0,staticfil:2,item:1,enumer:0,either:0,each:0,small:0,found:3,updat:1,where:[3,4],manag:[1,3],view:[0,3,4],pleas:1,set:[0,4],sortableadmin:[0,4],person:0,individu:1,some:0,sortablegenerictabularinlin:0,ensur:[2,4],see:[0,3],meta:[0,4],sampl:0,pass:[0,4],click:3,special:0,page:1,compat:1,index:[0,1],wire:4,insid:2,defin:[0,4],mysortabletabularinlin:0,abl:0,content:[],won:0,unit:3,rel:0,"new":[],foo:0,method:[0,2],note:0,attribut:[0,1],altern:2,core:[2,4],javascript:[0,2],run:3,parent:0,migrat:0,gener:0,sortabletabularinlin:0,here:[0,4],standard:0,base:[0,1],symlink:2,dictionari:0,few:[0,2],depend:0,"super":[0,1],valu:0,addit:0,search:1,wai:[0,1],change_form_template_extend:0,befor:0,column:0,latest:1,verbose_name_plur:0,filter:0,orm:0,includ:[0,2,3],fals:0,charfield:[0,4],chang:[0,1,3],sortablestackedinlin:0,honor:0,south:0,via:3,simpli:4,directli:3,extra:[0,4],instanti:0,appli:0,modul:1,independ:0,prefer:2,number:0,automat:0,due:0,change_form:0,right:0,contrib:0,instal:4,installed_app:[2,4],assum:0,your:[0,1,2,4],select:0,login:3,"class":[0,4],quit:2,from:[0,2,3,4],would:0,area:3,data:0,regist:[0,4],sometim:0,name:0,compon:0,start:4,max_length:[0,4],"__unicode__":[0,4],recommend:0,taken:3,inner:0,locat:2,tabularinlin:0,"function":3,properli:0,desir:4,option:[0,4],form:[0,3],ascend:0,tool:[3,4],copi:2,about:0,specifi:0,site:[0,4],forward:0,link:[0,3,4],tabularstackedinlin:0,line:0,inlin:[1,3],"true":0,present:[0,4],must:0,"case":0,anoth:0,made:1,look:[0,3],possibl:0,"default":0,directori:[2,3],change_list:0,displai:0,project:[0,2,3,4],record:3,below:[0,1],can:[0,2,3,4],caveat:0,foreignkei:0,"static":4,schema:0,booleanfield:0,def:[0,4],sort:[],sai:3,myapp:0,creat:0,quickstart:[],almost:1,credenti:3,changelist:4,sortablegenericstackedinlin:0,non:0,tabular:0,need:[0,4],inform:0,inherit:[0,4],have:[0,3,4],pip:4,mysortableadminclass:[0,4],work:[0,3],edit_inlin:0,normal:0,hit:0,incompat:[0,1],mysortableclass:[0,4],equival:0,get_is_sort:0,suggest:0,self:[0,4],format:[0,1],when:[3,4],same:0,member:0,also:[0,1],html:0,take:4,which:0,tupl:[0,1],test:[],instead:0,you:[0,1,2,3,4],properti:0,simpl:2,css:[0,2],difficult:0,mysortablestackedinlin:0,get_queryset:0,allow:0,stackedinlin:0,sorting_filt:[0,1],positivesmallinteg:0,why:0,after:0,director:0,peopl:0,drag:[1,3,4],two:0,thi:[0,3],mai:[0,1,3],change_list_template_extend:0,stack:0,appear:0,exactli:0,appropri:0,don:0,first_nam:0,ani:[0,1,3,4],widgetadmin:0,request:0,object:4,order:[0,1,3,4],height:0,more:[0,4],sample_project:3,exampl:0,determin:0,titl:[0,4],tall:0,model:[3,4],backward:[0,1],make:0,provid:0,left:0},objtypes:{},objnames:{},filenames:["usage","index","configuration","testing","quickstart"],titles:["Using Django Admin Sortable","Welcome to Django Admin Sortable’s documentation!","Configuring Django Admin Sortable","Testing","Quickstart"],objects:{},titleterms:{overrid:0,subset:0,quickstart:4,queryset:0,indic:1,exist:0,tabl:1,what:1,welcom:1,media:2,support:1,configur:2,custom:0,content:1,version:1,test:3,"new":1,document:1,higher:[],sort:0,sortabl:[0,1,2],extend:0,object:0,templat:0,inlin:0,admin:[0,1,2],django:[0,1,2],integr:0,"static":2,model:0}})

docs/_build/html/usage.html

@@ -0,0 +1,332 @@
+
+
+<!DOCTYPE html>
+<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
+<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  
+  <title>Using Django Admin Sortable &mdash; Django Admin Sortable 1.7.0 documentation</title>
+  
+
+  
+  
+
+  
+  <link href='https://fonts.googleapis.com/css?family=Lato:400,700,400italic,700italic|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
+
+  
+  
+    
+
+  
+
+  
+  
+    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
+  
+
+  
+    <link rel="top" title="Django Admin Sortable 1.7.0 documentation" href="index.html"/>
+        <link rel="next" title="Testing" href="testing.html"/>
+        <link rel="prev" title="Configuring Django Admin Sortable" href="configuration.html"/> 
+
+  
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
+
+</head>
+
+<body class="wy-body-for-nav" role="document">
+
+  <div class="wy-grid-for-nav">
+
+    
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-nav-search">
+        
+          <a href="index.html" class="fa fa-home"> Django Admin Sortable</a>
+        
+        <div role="search">
+  <form id ="rtd-search-form" class="wy-form" action="search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+      </div>
+
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+        
+        
+            <ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
+<li class="toctree-l1"><a class="reference internal" href="configuration.html">Configuring Django Admin Sortable</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="configuration.html#static-media">Static Media</a></li>
+</ul>
+</li>
+<li class="toctree-l1 current"><a class="current reference internal" href="">Using Django Admin Sortable</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#models">Models</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
+</ul>
+
+        
+      </div>
+      &nbsp;
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+
+      
+      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
+        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+        <a href="index.html">Django Admin Sortable</a>
+      </nav>
+
+
+      
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="index.html">Docs</a> &raquo;</li>
+      
+    <li>Using Django Admin Sortable</li>
+      <li class="wy-breadcrumbs-aside">
+        
+          <a href="_sources/usage.txt" rel="nofollow"> View page source</a>
+        
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document">
+            
+  <div class="section" id="using-django-admin-sortable">
+<h1>Using Django Admin Sortable<a class="headerlink" href="#using-django-admin-sortable" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="models">
+<h2>Models<a class="headerlink" href="#models" title="Permalink to this headline">¶</a></h2>
+<p>To add sorting to a model, your model needs to inherit from <code class="docutils literal"><span class="pre">Sortable</span></code> and have an inner <code class="docutils literal"><span class="pre">Meta</span></code> class that inherits from <code class="docutils literal"><span class="pre">Sortable.Meta</span></code>:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="c"># models.py</span>
+<span class="kn">from</span> <span class="nn">adminsortable.models</span> <span class="kn">import</span> <span class="n">Sortable</span>
+
+<span class="k">class</span> <span class="nc">MySortableClass</span><span class="p">(</span><span class="n">Sortable</span><span class="p">):</span>
+    <span class="k">class</span> <span class="nc">Meta</span><span class="p">(</span><span class="n">Sortable</span><span class="o">.</span><span class="n">Meta</span><span class="p">):</span>
+        <span class="k">pass</span>
+
+    <span class="n">title</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span>
+
+    <span class="k">def</span> <span class="nf">__unicode__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">title</span>
+</pre></div>
+</div>
+<p>It is also possible to order objects relative to another object that is a ForeignKey.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">A small caveat here is that <code class="docutils literal"><span class="pre">Category</span></code> must also either inherit from <code class="docutils literal"><span class="pre">Sortable</span></code> or include an <code class="docutils literal"><span class="pre">order</span></code> property which is a <code class="docutils literal"><span class="pre">PositiveSmallInteger</span></code> field. This is due to the way Django admin instantiates classes.</p>
+</div>
+<p><code class="docutils literal"><span class="pre">Sortable</span></code> has one field: <code class="docutils literal"><span class="pre">order</span></code> and adds a default ordering value set to <code class="docutils literal"><span class="pre">order</span></code>, ascending.</p>
+<div class="section" id="adding-sortable-to-an-existing-model">
+<h3>Adding Sortable to an existing model<a class="headerlink" href="#adding-sortable-to-an-existing-model" title="Permalink to this headline">¶</a></h3>
+<p>If you&#8217;re adding Sorting to an existing model, it is recommended that you use <a class="reference external" href="http://south.areacode.com/">django-south</a> to create a schema migration to add the &#8220;order&#8221; field to your model. You will also need to create a data migration in order to add the appropriate values for the <code class="docutils literal"><span class="pre">order</span></code> column.</p>
+<p>Example assuming a model named &#8220;Category&#8221;:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">forwards</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">orm</span><span class="p">):</span>
+    <span class="k">for</span> <span class="n">index</span><span class="p">,</span> <span class="n">category</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">orm</span><span class="o">.</span><span class="n">Category</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()):</span>
+        <span class="n">category</span><span class="o">.</span><span class="n">order</span> <span class="o">=</span> <span class="n">index</span> <span class="o">+</span> <span class="mi">1</span>
+        <span class="n">category</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>See <a class="reference external" href="http://south.readthedocs.org/en/latest/tutorial/part3.html">this link</a> for more information on Data Migrations.</p>
+</div>
+<div class="section" id="django-admin-integration">
+<h3>Django Admin Integration<a class="headerlink" href="#django-admin-integration" title="Permalink to this headline">¶</a></h3>
+<p>To enable sorting in the admin, you need to inherit from <code class="docutils literal"><span class="pre">SortableAdmin</span></code>:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.contrib</span> <span class="kn">import</span> <span class="n">admin</span>
+<span class="kn">from</span> <span class="nn">myapp.models</span> <span class="kn">import</span> <span class="n">MySortableClass</span>
+<span class="kn">from</span> <span class="nn">adminsortable.admin</span> <span class="kn">import</span> <span class="n">SortableAdmin</span>
+
+<span class="k">class</span> <span class="nc">MySortableAdminClass</span><span class="p">(</span><span class="n">SortableAdmin</span><span class="p">):</span>
+    <span class="sd">&quot;&quot;&quot;Any admin options you need go here&quot;&quot;&quot;</span>
+
+<span class="n">admin</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">MySortableClass</span><span class="p">,</span> <span class="n">MySortableAdminClass</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>To enable sorting on TabularInline models, you need to inherit from SortableTabularInline:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">adminsortable.admin</span> <span class="kn">import</span> <span class="n">SortableTabularInline</span>
+
+<span class="k">class</span> <span class="nc">MySortableTabularInline</span><span class="p">(</span><span class="n">SortableTabularInline</span><span class="p">):</span>
+    <span class="sd">&quot;&quot;&quot;Your inline options go here&quot;&quot;&quot;</span>
+</pre></div>
+</div>
+<p>To enable sorting on StackedInline models, you need to inherit from SortableStackedInline:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">adminsortable.admin</span> <span class="kn">import</span> <span class="n">SortableStackedInline</span>
+
+<span class="k">class</span> <span class="nc">MySortableStackedInline</span><span class="p">(</span><span class="n">SortableStackedInline</span><span class="p">):</span>
+    <span class="sd">&quot;&quot;&quot;Your inline options go here&quot;&quot;&quot;</span>
+</pre></div>
+</div>
+<p>There are also generic equivalents that you can inherit from:</p>
+<div class="highlight-python"><div class="highlight"><pre>from adminsortable.admin import (SortableGenericTabularInline,
+    SortableGenericStackedInline)
+    &quot;&quot;&quot;Your generic inline options go here&quot;&quot;&quot;
+</pre></div>
+</div>
+</div>
+<div class="section" id="overriding-queryset">
+<h3>Overriding <code class="docutils literal"><span class="pre">queryset()</span></code><a class="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&#8217;re providing an override of a <code class="docutils literal"><span class="pre">SortableAdmin</span></code> or <code class="docutils literal"><span class="pre">Sortable</span></code> inline model, you don&#8217;t need to do anything extra. django-admin-sortable will automatically honor your queryset.</p>
+<p>Have a look at the <code class="docutils literal"><span class="pre">WidgetAdmin</span></code> class in the sample project for an example of an admin class with a custom <code class="docutils literal"><span class="pre">queryset()</span></code> override.</p>
+</div>
+<div class="section" id="overriding-queryset-for-an-inline-model">
+<h3>Overriding <code class="docutils literal"><span class="pre">queryset()</span></code> for an inline model<a class="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>
+<div class="highlight-python"><div class="highlight"><pre><span class="c"># add this import to your admin.py</span>
+<span class="kn">from</span> <span class="nn">adminsortable.utils</span> <span class="kn">import</span> <span class="n">get_is_sortable</span>
+
+
+<span class="k">class</span> <span class="nc">ComponentInline</span><span class="p">(</span><span class="n">SortableStackedInline</span><span class="p">):</span>
+    <span class="n">model</span> <span class="o">=</span> <span class="n">Component</span>
+
+    <span class="k">def</span> <span class="nf">queryset</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
+        <span class="n">qs</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">ComponentInline</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">queryset</span><span class="p">(</span><span class="n">request</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
+            <span class="n">title__icontains</span><span class="o">=</span><span class="s">&#39;foo&#39;</span><span class="p">)</span>
+
+        <span class="c"># You&#39;ll need to add these lines to determine if your model</span>
+        <span class="c"># is sortable once we hit the change_form() for the parent model.</span>
+
+        <span class="k">if</span> <span class="n">get_is_sortable</span><span class="p">(</span><span class="n">qs</span><span class="p">):</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="o">.</span><span class="n">is_sortable</span> <span class="o">=</span> <span class="bp">True</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="o">.</span><span class="n">is_sortable</span> <span class="o">=</span> <span class="bp">False</span>
+        <span class="k">return</span> <span class="n">qs</span>
+</pre></div>
+</div>
+<p>If you override the queryset of an inline, the number of objects present may change, and adminsortable won&#8217;t be able to automatically determine if the inline model is sortable from here, which is why we have to set the <code class="docutils literal"><span class="pre">is_sortable</span></code> property of the model in this method.</p>
+</div>
+<div class="section" id="sorting-subsets-of-objects">
+<h3>Sorting subsets of objects<a class="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 <code class="docutils literal"><span class="pre">sorting_filters</span></code> tuple. This works exactly the same as <code class="docutils literal"><span class="pre">.filter()</span></code> on a QuerySet, and is applied <em>after</em> <code class="docutils literal"><span class="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 &#8220;Change Order of&#8221; 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 <code class="docutils literal"><span class="pre">sorting_filters</span></code> are specified, the text &#8220;Change Order&#8221; will be displayed for the link.</p>
+<p>An example of sorting subsets would be a &#8220;Board of Directors&#8221;. In this use case, you have a list of &#8220;People&#8221; objects. Some of these people are on the Board of Directors and some not, and you need to sort them independently:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Person</span><span class="p">(</span><span class="n">Sortable</span><span class="p">):</span>
+    <span class="k">class</span> <span class="nc">Meta</span><span class="p">(</span><span class="n">Sortable</span><span class="o">.</span><span class="n">Meta</span><span class="p">):</span>
+        <span class="n">verbose_name_plural</span> <span class="o">=</span> <span class="s">&#39;People&#39;</span>
+
+    <span class="n">first_name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span>
+    <span class="n">last_name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span>
+    <span class="n">is_board_member</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">BooleanField</span><span class="p">(</span><span class="s">&#39;Board Member&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
+
+    <span class="n">sorting_filters</span> <span class="o">=</span> <span class="p">(</span>
+        <span class="p">(</span><span class="s">&#39;Board Members&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s">&#39;is_board_member&#39;</span><span class="p">:</span> <span class="bp">True</span><span class="p">}),</span>
+        <span class="p">(</span><span class="s">&#39;Non-Board Members&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s">&#39;is_board_member&#39;</span><span class="p">:</span> <span class="bp">False</span><span class="p">}),</span>
+    <span class="p">)</span>
+
+    <span class="k">def</span> <span class="nf">__unicode__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">return</span> <span class="s">&#39;{} {}&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">first_name</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">last_name</span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">django-admin-sortable 1.6.6 introduces a backwards-incompatible change for <code class="docutils literal"><span class="pre">sorting_filters</span></code>. Previously this attribute was defined as a dictionary, so you&#8217;ll need to change your values over to the new tuple-based format.</p>
+</div>
+</div>
+<div class="section" id="extending-custom-templates">
+<h3>Extending custom templates<a class="headerlink" href="#extending-custom-templates" title="Permalink to this headline">¶</a></h3>
+<p>By default, adminsortable&#8217;s change form and change list views inherit from Django admin&#8217;s standard templates. Sometimes you need to have a custom change form or change list, but also need adminsortable&#8217;s CSS and JavaScript for inline models that are sortable for example.</p>
+<p><code class="docutils literal"><span class="pre">SortableAdmin</span></code> has two attributes you can override for this use case:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">change_form_template_extends</span>
+<span class="n">change_list_template_extends</span>
+</pre></div>
+</div>
+<p>These attributes have default values of:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">change_form_template_extends</span> <span class="o">=</span> <span class="s">&#39;admin/change_form.html&#39;</span>
+<span class="n">change_list_template_extends</span> <span class="o">=</span> <span class="s">&#39;admin/change_list.html&#39;</span>
+</pre></div>
+</div>
+<p>If you need to extend the inline change form templates, you&#8217;ll need to select the right one, depending on your version of Django. For Django 1.5.x or below, you&#8217;ll need to extend one of the following:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">templates</span><span class="o">/</span><span class="n">adminsortable</span><span class="o">/</span><span class="n">edit_inline</span><span class="o">/</span><span class="n">stacked</span><span class="o">-</span><span class="mf">1.5</span><span class="o">.</span><span class="n">x</span><span class="o">.</span><span class="n">html</span>
+<span class="n">templates</span><span class="o">/</span><span class="n">adminsortable</span><span class="o">/</span><span class="n">edit_inline</span><span class="o">/</span><span class="n">tabular</span><span class="o">-</span><span class="n">inline</span><span class="o">-</span><span class="mf">1.5</span><span class="o">.</span><span class="n">x</span><span class="o">.</span><span class="n">html</span>
+</pre></div>
+</div>
+<p>For Django &gt;= 1.6.x, extend:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">templates</span><span class="o">/</span><span class="n">adminsortable</span><span class="o">/</span><span class="n">edit_inline</span><span class="o">/</span><span class="n">stacked</span><span class="o">.</span><span class="n">html</span>
+<span class="n">templates</span><span class="o">/</span><span class="n">adminsortable</span><span class="o">/</span><span class="n">edit_inline</span><span class="o">/</span><span class="n">tabular</span><span class="o">.</span><span class="n">html</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="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>
+</div>
+</div>
+</div>
+</div>
+
+
+          </div>
+          <footer>
+  
+    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
+      
+        <a href="testing.html" class="btn btn-neutral float-right" title="Testing">Next <span class="fa fa-arrow-circle-right"></span></a>
+      
+      
+        <a href="configuration.html" class="btn btn-neutral" title="Configuring Django Admin Sortable"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+      
+    </div>
+  
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>
+        &copy; Copyright 2014, Brandon Taylor.
+    </p>
+  </div>
+
+  <a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>
+</footer>
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+  
+
+
+  
+
+    <script type="text/javascript">
+        var DOCUMENTATION_OPTIONS = {
+            URL_ROOT:'./',
+            VERSION:'1.7.0',
+            COLLAPSE_INDEX:false,
+            FILE_SUFFIX:'.html',
+            HAS_SOURCE:  true
+        };
+    </script>
+      <script type="text/javascript" src="_static/jquery.js"></script>
+      <script type="text/javascript" src="_static/underscore.js"></script>
+      <script type="text/javascript" src="_static/doctools.js"></script>
+
+  
+
+  
+  
+    <script type="text/javascript" src="_static/js/theme.js"></script>
+  
+
+  
+  
+  <script type="text/javascript">
+      jQuery(function () {
+          SphinxRtdTheme.StickyNav.enable();
+      });
+  </script>
+   
+
+</body>
+</html>

docs/usage.rst

@@ -0,0 +1,167 @@
+Using Django Admin Sortable
+===========================
+
+Models
+------
+
+To add sorting to a model, your model needs to inherit from ``Sortable`` and have an inner ``Meta`` class that inherits from ``Sortable.Meta``::
+
+    # models.py
+    from adminsortable.models import Sortable
+
+    class MySortableClass(Sortable):
+        class Meta(Sortable.Meta):
+            pass
+
+        title = models.CharField(max_length=50)
+
+        def __unicode__(self):
+            return self.title
+
+It is also possible to order objects relative to another object that is a ForeignKey.
+
+.. note:: A small caveat here is that ``Category`` must also either inherit from ``Sortable`` or include an ``order`` property which is a ``PositiveSmallInteger`` field. This is due to the way Django admin instantiates classes.
+
+``Sortable`` has one field: ``order`` and adds a default ordering value set to ``order``, ascending.
+
+Adding Sortable to an existing model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you're adding Sorting to an existing model, it is recommended that you use `django-south <http://south.areacode.com/>`_ 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 ``order`` column.
+
+Example assuming a model named "Category"::
+
+    def forwards(self, orm):
+        for index, category in enumerate(orm.Category.objects.all()):
+            category.order = index + 1
+            category.save()
+
+See `this link <http://south.readthedocs.org/en/latest/tutorial/part3.html>`_ for more information on Data Migrations.
+
+Django Admin Integration
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To enable sorting in the admin, you need to inherit from ``SortableAdmin``::
+
+        from django.contrib import admin
+        from myapp.models import MySortableClass
+        from adminsortable.admin import SortableAdmin
+
+        class MySortableAdminClass(SortableAdmin):
+            """Any admin options you need go here"""
+
+        admin.site.register(MySortableClass, MySortableAdminClass)
+
+To enable sorting on TabularInline models, you need to inherit from SortableTabularInline::
+
+    from adminsortable.admin import SortableTabularInline
+
+    class MySortableTabularInline(SortableTabularInline):
+        """Your inline options go here"""
+
+To enable sorting on StackedInline models, you need to inherit from SortableStackedInline::
+
+    from adminsortable.admin import SortableStackedInline
+
+    class MySortableStackedInline(SortableStackedInline):
+        """Your inline options go here"""
+
+There are also generic equivalents that you can inherit from::
+
+    from adminsortable.admin import (SortableGenericTabularInline,
+        SortableGenericStackedInline)
+        """Your generic inline options go here"""
+
+Overriding ``queryset()``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+django-admin-sortable supports custom queryset overrides on admin models and inline models in Django admin!
+
+If you're providing an override of a ``SortableAdmin`` or ``Sortable`` inline model, you don't need to do anything extra. django-admin-sortable will automatically honor your queryset.
+
+Have a look at the ``WidgetAdmin`` class in the sample project for an example of an admin class with a custom ``queryset()`` override.
+
+Overriding ``queryset()`` for an inline model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is a special case, which requires a few lines of extra code to properly determine the sortability of your model. Example::
+
+    # add this import to your admin.py
+    from adminsortable.utils import get_is_sortable
+
+
+    class ComponentInline(SortableStackedInline):
+        model = Component
+
+        def queryset(self, request):
+            qs = super(ComponentInline, self).queryset(request).filter(
+                title__icontains='foo')
+
+            # You'll need to add these lines to determine if your model
+            # is sortable once we hit the change_form() for the parent model.
+
+            if get_is_sortable(qs):
+                self.model.is_sortable = True
+            else:
+                self.model.is_sortable = False
+            return qs
+
+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 ``is_sortable`` property of the model in this method.
+
+Sorting subsets of objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is also possible to sort a subset of objects in your model by adding a ``sorting_filters`` tuple. This works exactly the same as ``.filter()`` on a QuerySet, and is applied *after* ``get_queryset()`` 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 ``sorting_filters`` are specified, the text "Change Order" will be displayed for the link.
+
+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::
+
+    class Person(Sortable):
+        class Meta(Sortable.Meta):
+            verbose_name_plural = 'People'
+
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+        is_board_member = models.BooleanField('Board Member', default=False)
+
+        sorting_filters = (
+            ('Board Members', {'is_board_member': True}),
+            ('Non-Board Members', {'is_board_member': False}),
+        )
+
+        def __unicode__(self):
+            return '{} {}'.format(self.first_name, self.last_name)
+
+
+.. warning::
+
+    django-admin-sortable 1.6.6 introduces a backwards-incompatible change for ``sorting_filters``. Previously this attribute was defined as a dictionary, so you'll need to change your values over to the new tuple-based format.
+
+Extending custom templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+``SortableAdmin`` has two attributes you can override for this use case::
+
+    change_form_template_extends
+    change_list_template_extends
+
+These attributes have default values of::
+
+    change_form_template_extends = 'admin/change_form.html'
+    change_list_template_extends = 'admin/change_list.html'
+
+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::
+
+    templates/adminsortable/edit_inline/stacked-1.5.x.html
+    templates/adminsortable/edit_inline/tabular-inline-1.5.x.html
+
+For Django >= 1.6.x, extend::
+
+    templates/adminsortable/edit_inline/stacked.html
+    templates/adminsortable/edit_inline/tabular.html
+
+.. note::
+
+    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.