=============
admin-sortable
=============

What is it?
=============
The adminsortable app adds generic drag-and-drop facilities
to any Django model class or Tabular Inline via Django Admin
and jQueryUI.

Installation
=============
1. Run ``setup.py`` or add ``adminsortable`` to your PYTHONPATH.
2. Copy the ``adminsortable`` folder from the media folder to the
location you server static files from.
3. Add ``adminsortable`` to your INSTALLED_APPS.
4. Have a look at the included sample_project to see working examples.

When a model is sortable, a tool-area link will be added that says "Change Order".
Click this link, and you will be taken to the custom view where you can drag-and-drop
the records into order.

Tabular inlines may be drag-and-dropped into any order directly from the change form.

Usage
=============
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)
        
        title = models.CharField(max_length=50)
        
        def __unicode__(self):
            return self.title


For models that you want sortable relative to a ``ForeignKey`` field, you need to
specify an ``@classmethod`` that returns a double: the foreign key class, and the
name of the foreign key property as defined on your model, as a string.

    #admin.py
    class Category(models.Model):
        title = models.CharField(max_length=50)
        ...
    
    class MySortableClass(Sortable):
        class Meta(Sortable.Meta)
        
        category = models.ForeignKey(Category)
        title = models.CharField(max_length=50)
        
        def __unicode__(self):
            return self.title
        
        @classmethod
        def sortable_by(cls):
            return Category, 'category'


Sortable has one field: `order` and adds a default ordering value set to `order`.

South
------
If you're adding Sorting to an existing model, it is recommended that you use django-south,
http://south.areacode.com/ to create a migration to add the "order" field to your model.


*Django Admin Usage*
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"""


Rationale
=============
Other projects have added drag-and-drop ordering to the ChangeList
view, however this introduces a couple of problems...

- The ChangeList view supports pagination, which makes drag-and-drop
ordering across pages impossible.
- The ChangeList view by default, does not order records based on a
foreign key, nor distinguish between rows that are associated with a
foreign key. This makes ordering the records grouped by a foreign key
impossible.
- The ChangeList supports in-line editing, and adding drag-and-drop
ordering on top of that just seemed a little much in my opinion.

Status
=============
admin-sortable is currently used in production.

Feautures
=============
Current
---------
- Supports Django 1.3+
- Adds an admin view to any model that inherits from Sortable and SortableAdmin
that allows you to drag and drop objects into any order via jQueryUI.
- Adds drag and drop ordering to Tabular Inline models that inherit from
SortableTabularInline
- Allows ordering of objects that are sorted on a Foreign Key, and adds ordering
to the foreign key object if it also inherits from Sortable.

Future
------
- Support for foreign keys that are self referential
- Support for StackedInline
- Support for ForeignKeys that have not been previously defined

Requirements
=============
Sample Project
----------------
Requires django-appmedia, included

License
=============
The admin-sortable app is released 
under the Apache Public License v2.