=============
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.
4e38d8fbe1