https://github.com/inueni/django-subadmin
A special kind of ModelAdmin that allows it to be nested within another ModelAdmin
https://github.com/inueni/django-subadmin
django django-admin python
Last synced: 8 months ago
JSON representation
A special kind of ModelAdmin that allows it to be nested within another ModelAdmin
- Host: GitHub
- URL: https://github.com/inueni/django-subadmin
- Owner: inueni
- License: mit
- Created: 2017-11-12T23:52:27.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2024-09-03T22:26:13.000Z (about 1 year ago)
- Last Synced: 2024-09-23T13:48:27.411Z (about 1 year ago)
- Topics: django, django-admin, python
- Language: Python
- Homepage:
- Size: 40 KB
- Stars: 141
- Watchers: 8
- Forks: 18
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# django-subadmin
`django-subadmin` provides a special kind of `ModelAdmin`, called `SubAdmin`, that allows it to be nested within another `ModelAdmin` instance. Similar to django's built-in `InlineModelAdmin`, it allows editing of related objects, but instead of doing it inline, it gives you a full `ModelAdmin` as sub-admin of parent `ModelAdmin`. Like `InlineModelAdmin` it works on models related by `ForeignKey`. Multiple `SubAdmin` instances can be nested within a single `ModelAdmin` or `SubAdmin` allowing for multi-level nesting.
### Supported Python and Django releases
Current release of `django-subadmin` supports Django versions 3.2 and up (including Django 4).
#### Verison numbering
django-subadmin versions follow Django version numbers. django-subadmin major and minor version numbers equal the minimal compatible django release.
## Installation
The easiest and recommended way to install `django-subadmin` is from [PyPI](https://pypi.python.org/pypi/django-subadmin)
```
pip install django-subadmin
```
You need to add `subadmin` to `INSTALLED_APPS` in your projects `settings.py`, otherwise `django` will not be able to find the necessary templates and template tags.
```
# settings.py
INSTALLED_APPS = (
...
'subadmin',
...
)
```
## Example Usage
Sometimes things are best explained by an example. Let's say you have two related models.
```python
# models.py
class MailingList(models.Model):
name = models.CharField(max_length=100)
class Subscriber(models.Model):
mailing_list = models.ForeignKey(MailingList)
username = models.CharField(max_length=100)
```
If you wish to display only subscribers belonging to a particular mailing list in django admin, your only option is to use `InlineModelAdmin`, which is not very practical when dealing with a large number of related objects, plus, you loose all the cool functionality of `ModelAdmin` like searching, filtering, pagination, etc ...
This is where `SubAdmin` comes in.
```python
# admin.py
from subadmin import SubAdmin, RootSubAdmin
from .models import MailingList, Subscriber
# Instead of admin.ModelAdmin we subclass SubAdmin,
# we also set model attribute
class SubscriberSubAdmin(SubAdmin):
model = Subscriber
list_display = ('username',)
# Since this is the top level model admin, which will be registred with admin.site,
# we subclass RootSubAdmin and set subadmins attribute
class MailingListAdmin(RootSubAdmin):
list_display = ('name',)
subadmins = [SubscriberSubAdmin]
admin.site.register(MailingList, MailingListAdmin)
```
With just a few lines of code you get a fully functional `ModelAdmin`, that will automatically pull in just the relevant related objects, based on `ForeignKey` relation between the two models, it will also auto set `ForeignKey` fields for nested relations and exclude them from change form when adding and editing objects on subadmin.
### Caveats
In order to properly support unique field validation (see Issue #7), `SubAdmin` will inject a small mixin into the form. This is done in the `get_form` method and if you override this method in your own classes, make sure to call `super()` or `perp_subadmin_form()` directly. See `subadmin` source code for more details.
Also, the injected mixin `SubAdminFormMixin` overrides `validate_unique` on the form. If your custom form overrides this method as well, have a look at `subadmin` source code for ways in which it differs from the stock `ModelForm` implementation and adjust your code as necessary.
### Screenshots
`SubAdmin` instances are accessible from edit view of the `ModelAdmin` instance they are nested in. In the screenshot above you can see links to _Subscribers_ and _Messages_ subadmins (marked with red rectangle) for `MailingList` instance _Mailing list 5_.
---
`SubAdmin` looks and behaves just like a regular `ModelAdmin`, but looking at breadcrumbs (marked with red rectangle), you can see it is nested within another `ModelAdmin`. Displayed `Subscribers` are limited to those related to `MailingList` instance _Mailing list 5_.
---
When adding or editing objects with `SubAdmin`, `ForeignKey` fields to parent instances are removed from the form and automatically set when saving. In this example `mailing_list` field is removed and value is set to parent `MailingList` instance _Mailing list 5_.
> If you want to see it in action, or get a more in-depth look at how to set everything up, check out .
## Stability
`django-subadmin` has evolved from code that has been running on production servers since early 2014 without any issues. The code is provided **as-is** and the developers bear no responsibility for any issues stemming from it's use.