django-admin-sortable 2.1.12

Common Use Case

A common use case is to have child objects that are sortable relative to a parent. If your parent object is also sortable, here’s how you would set up your models and admin options:

# models.py
from adminsortable.fields import SortableForeignKey

class Category(SortableMixin):
    class Meta:
        ordering = ['category_order']
        verbose_name_plural = 'Categories'

    title = models.CharField(max_length=50)

    # ordering field
    category_order = models.PositiveIntegerField(default=0, editable=False, db_index=True)

class Project(SortableMixin):
    class Meta:
        ordering = ['project_order']

    category = SortableForeignKey(Category)
    title = models.CharField(max_length=50)

    # ordering field
    project_order = models.PositiveIntegerField(default=0, editable=False, db_index=True)

    def __unicode__(self):
        return self.title

# admin.py
from adminsortable.admin import SortableAdmin

from your_app.models import Category, Project

admin.site.register(Category, SortableAdmin)
admin.site.register(Project, SortableAdmin)

Sometimes you might have a parent model that is not sortable, but has child models that are. In that case define your models and admin options as such:

from adminsortable.fields import SortableForeignKey

# models.py
class Category(models.Model):
    class Meta:
        verbose_name_plural = 'Categories'

    title = models.CharField(max_length=50)
    ...

class Project(SortableMixin):
    class Meta:
        ordering = ['project_order']

    category = SortableForeignKey(Category)
    title = models.CharField(max_length=50)

    # ordering field
    project_order = models.PositiveIntegerField(default=0, editable=False, db_index=True)

    def __unicode__(self):
        return self.title

# admin
from adminsortable.admin import NonSortableParentAdmin, SortableStackedInline

from your_app.models import Category, Project

class ProjectInline(SortableStackedInline):
    model = Project
    extra = 1

class CategoryAdmin(NonSortableParentAdmin):
    inlines = [ProjectInline]

admin.site.register(Category, CategoryAdmin)

The NonSortableParentAdmin class is necessary to wire up the additional URL patterns and JavaScript that Django Admin Sortable needs to make your models sortable. The child model does not have to be an inline model, it can be wired directly to Django admin and the objects will be grouped by the non-sortable foreign key when sorting.

Model Instance Methods

Each instance of a sortable model has two convenience methods to get the next or previous instance:

.get_next()
.get_previous()

By default, these methods will respect their order in relation to a SortableForeignKey field, if present. Meaning, that given the following data:

| Parent Model 1 |               |
|                | Child Model 1 |
|                | Child Model 2 |
| Parent Model 2 |               |
|                | Child Model 3 |
|                | Child Model 4 |
|                | Child Model 5 |

“Child Model 2” get_next() would return None “Child Model 3” get_previous would return None

If you wish to override this behavior, pass in: filter_on_sortable_fk=False:

your_instance.get_next(filter_on_sortable_fk=False)

You may also pass in additional ORM “filer_args” as a list, or “filter_kwargs” as a dictionary, should you need to:

your_instance.get_next(
    filter_args=[Q(field1=True) | Q(field2=True)],
    filter_kwargs={'title__icontains': 'blue'}
)

Deprecation Warning

Previously “filter_kwargs” was named “extra_filters”. With the addition of “filter_args”, “extra_filters” was renamed for consistency. “extra_filters” will be removed in the next version of django-admin-sortable.

Django 1.5.x to 1.6.x

If you’re adding Sorting to an existing model, it is recommended that you use django-south 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 for more information on South Data Migrations.

Django 1.7.x or higher

Since schema migrations are built into Django 1.7, you don’t have to use south, but the process of adding and running migrations is nearly identical. Take a look at the Migrations documentation to get started.

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.

Self-Referential SortableForeignKey

You can specify a self-referential SortableForeignKey field, however the admin interface will currently show a model that is a grandchild at the same level as a child. I’m working to resolve this issue.

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)

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 1.10.x or below, you’ll need to extend one of the following:

templates/adminsortable/edit_inline/stacked-1.10.x.html
templates/adminsortable/edit_inline/tabular-inline-1.10.x.html

otherwise, extend:

templates/adminsortable/edit_inline/stacked.html
templates/adminsortable/edit_inline/tabular.html

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 SortableTabularInline instead.

Custom JS callbacks after sorting is complete

If you need to define a custom event or other callback to be executed after sorting is completed, you’ll need to:

1. Create a custom template for to add your JavaScript

2. Populate the after_sorting_js_callback_name on your model admin

An example of this can be found in the “samples” application in the source. Here’s a model admin for a model called “Project”:

class ProjectAdmin(SortableAdmin):
    inlines = [
        CreditInline, NoteInline, GenericNoteInline,
        NonSortableCreditInline, NonSortableNoteInline
    ]
    list_display = ['__str__', 'category']

    after_sorting_js_callback_name = 'afterSortCallback'  # do not include () - just function name
    sortable_change_list_template = 'adminsortable/custom_change_list.html'
    sortable_change_form_template = "adminsortable/custom_change_form.html"

This example is going to add a custom callback on the parent model, and it’s inlines. Here is the JavaScript added to the custom change list:

{% extends 'adminsortable/change_list.html' %}

{% block extrahead %}
  {{ block.super }}

  <script>
    django.jQuery(document).on('order:changed', function(event) {
      console.log(event.message);
      // your code here
    });

    window['{{ after_sorting_js_callback_name }}'] = function() {
      django.jQuery(document).trigger({ type: 'order:changed', message: 'Order changed', time: new Date() });
    };
  </script>
{% endblock %}

and the custom change form, for the inline models:

{% extends "adminsortable/change_form.html" %}

{% block extrahead %}
  {{ block.super }}

  <script>
    django.jQuery(document).on('order:changed', function(event) {
      console.log(event.message);
      // your code here
    });

    window['{{ after_sorting_js_callback_name }}'] = function() {
      django.jQuery(document).trigger({ type: 'order:changed', message: 'Order changed', time: new Date() });
    };
  </script>
{% endblock %}

Ideally, you’d pull in a shared piece of code for your callback to keep your code DRY.