django-ordered-model

Warnings

• breaking Subclasses of `OrderedModelBase` (including `OrderedModel`) must explicitly specify `Meta.ordering`. Failing to do so will emit a system `Check` failure since version 3.7.
  Fix: Ensure your model's `Meta` class includes `ordering = ("order",)` (or your custom order field name) or directly inherits from `OrderedModel.Meta`.
• breaking Since version 3.7, updating fields that are part of `order_with_respect_to` now correctly adjusts the ordering. This is a behavioral change that might impact existing logic if it relied on the previous, potentially incorrect, behavior.
  Fix: Review any code that modifies fields specified in `order_with_respect_to` to ensure the new auto-adjustment of ordering is desirable. Test thoroughly.
• gotcha If you use a custom `ModelManager` or `QuerySet` with an `OrderedModel`, they must inherit from `OrderedModelManager` or `OrderedModelQuerySet` respectively. Failing to do so will raise Django `Check` errors (E003/E004). As of 3.7.4, this is relaxed to a warning if the manager returns the correct queryset.
  Fix: Ensure your custom manager inherits from `OrderedModelManager` and your custom queryset from `OrderedModelQuerySet`. See the `django-ordered-model` README for examples of intermediate classes with multiple inheritance if needed.
• gotcha When using `order_with_respect_to`, the library implicitly sets an internal `_order` field for ordering. Therefore, `order_with_respect_to` and `Meta.ordering` cannot be used simultaneously in the same model's `Meta` class and will raise a Django error.
  Fix: Do not specify `Meta.ordering` when `order_with_respect_to` is already defined, as the ordering is implicitly handled by the `_order` field created by `order_with_respect_to`.
• gotcha Methods like `to()`, `up()`, `down()`, `top()`, `bottom()`, and `delete()` use Django's `update()` method for performance when shifting other objects. This means custom `save()` logic or `DateTimeField(auto_now=True)` on *other shifted objects* will not be called. For the target object itself, `save()` is called if not directly manipulating `order` field.
  Fix: If you need `save()` logic or `auto_now` fields to update on *shifted objects*, use the `extra_update` parameter on ordering methods (e.g., `item.to(new_pos, extra_update={'modified': timezone.now()})`).
• gotcha Django's `ManyToManyField` does not inherently respect `Meta.ordering` on intermediate (through) models when querying the 'members' queryset (e.g., `pizza.toppings.all()`).
  Fix: Use `ordered_model.fields.OrderedManyToManyField` or explicitly add an `order_by()` clause to your ManyToMany queryset (e.g., `pizza.toppings.all().order_by('pizzatoppingsthroughmodel__order')`).

Install

• pip install django-ordered-model Install stable version

Imports

• OrderedModel

  from ordered_model.models import OrderedModel

• OrderedModelBase

  from ordered_model.models import OrderedModelBase

  Use this base class if you want to use an existing field for ordering or customize the order field name.
• OrderedModelManager

  from ordered_model.models import OrderedModelManager

  Required if you use a custom ModelManager; it must inherit from this class.
• OrderedModelQuerySet

  from ordered_model.models import OrderedModelQuerySet

  Required if your custom ModelManager returns a custom QuerySet; it must inherit from this class.
• OrderedModelAdmin

  from ordered_model.admin import OrderedModelAdmin

  For integrating ordering controls into the Django admin.
• OrderedModelSerializer

  from ordered_model.serializers import OrderedModelSerializer

  For integrating ordering into Django REST Framework serializers.
• OrderedManyToManyField

  from ordered_model.fields import OrderedManyToManyField

  Use this field for ManyToMany relationships to ensure correct ordering on the 'members' queryset.
• OrderedTabularInline

  from ordered_model.admin import OrderedTabularInline

  For reordering ManyToMany relationships in the admin via a tabular inline.

Quickstart

Define a model inheriting from `OrderedModel` and register it with `OrderedModelAdmin` in the Django admin to enable reordering functionality. Ensure 'ordered_model' is in `INSTALLED_APPS` and run migrations.

from django.db import models
from django.contrib import admin
from ordered_model.models import OrderedModel
from ordered_model.admin import OrderedModelAdmin

# models.py
class Item(OrderedModel):
    name = models.CharField(max_length=100)

    class Meta(OrderedModel.Meta):
        verbose_name = "Item"
        verbose_name_plural = "Items"

# admin.py
class ItemAdmin(OrderedModelAdmin):
    list_display = ('name', 'move_up_down_links')

admin.site.register(Item, ItemAdmin)