Metadata-Version: 2.4
Name: django-reorder-items-widget
Version: 1.1.1
Summary: Easily reorder the order of items within the django admin backend.
Author-email: Thomas Leichtfuß <thomas.leichtfuss@posteo.de>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/thomst/django-reorder-items-widget
Project-URL: Repository, https://github.com/thomst/django-reorder-items-widget
Project-URL: Documentation, https://github.com/thomst/django-reorder-items-widget#readme
Keywords: django,django-admin,widgets
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: Django>=3.2
Dynamic: license-file

# Welcome to django-reorder-items-widget

[![Tests](https://github.com/thomst/django-reorder-items-widget/actions/workflows/tests.yml/badge.svg)](https://github.com/thomst/django-reorder-items-widget/actions/workflows/tests.yml)
[<img src="https://coveralls.io/repos/github/thomst/django-reorder-items-widget/badge.svg?branch=main">](https://coveralls.io/github/thomst/django-reorder-items-widget?branch=main)
[<img src="https://img.shields.io/badge/python-3-blue">](https://img.shields.io/badge/python-3-blue)
[<img src="https://img.shields.io/badge/django-3.2%20%7C%204.0%20%7C%204.1%20%7C%204.2%20%7C%205.0%20%7C%205.1%20%7C%205.2%20%7C%206.0-orange">](https://img.shields.io/badge/django-3.2%20%7C%204.0%20%7C%204.1%20%7C%204.2%20%7C%205.0%20%7C%205.1%20%7C%205.2%20%7C%206.0-orange)


## Description

Reorder your items by simply dragging them to their new position. This works
fine within django admin's changelists or inline model forms.

All you need to do is to use an editable index field with the famous
`ReorderItemsWidget` of this app.


## Installation

Install via pip:
```
pip install django-reorder-items-widget
```

## Setup

Add `reorder_items_widget` to your `INSTALLED_APPS`:
```
INSTALLED_APPS = [
    'reorder_items_widget',
    ...
]
```

Add a index field to your model:
```
class Item(models.Model):
    index = models.PositiveSmallIntegerField()
    ...
    class Meta:
        ordering = ('index',)
```

Using the ReorderItemsWidget with your index field only makes sense in result
lists or inline modeladmin forms. A simple way to put the widget in place is a
custom model form:
```
class ReorderItemForm(forms.ModelForm):
    class Meta:
        widgets={'index': ReorderItemsWidget()}
```

Now you can use this form with your changelist by overwriting the
`get_changelist_form` method of your model admin:
```
class BaseItemAdmin(admin.ModelAdmin):
    list_editable = ("index",)
    list_display = ("index", ...)

    def get_changelist_form(self, request, **kwargs):
        kwargs.setdefault('form', ReorderItemForm)
        return super().get_changelist_form(request, **kwargs)
```

**_NOTE:_** Mind that your index field must be editable.

To use the widget with your inline modeladmin simple at your form to the
`TabularInline` class:
```
class ItemInline(admin.TabularInline):
    form = ReorderItemForm
    fields = ("index", ...)
    ...
```

That's it.

## Caveats

The widget will always number your items sequentially. So reordering a filtered
list of items might have unexpected results. Paging however should not be an
issue since indexes are updated using the index of the first list item as base.

## General considerations on switching index values

There is a general issue with switching values on a unique index field: In
mysql like databases you will run into a constraint violation - even if you
update all items in a single update transaction.

To work around this you can either obmit the unique constraint. Or implement a
complex saving logic like using the negative counterparts of your indexes in a
preceding update round and finally switch those values back to their positive
equivalent.

## Contribute

Feedback, feature requests, bug reports or pull requests are most welcome. Just
use the common github infrastructure.
