1
0
django-changelist-inline/README.rst

202 lines
6.6 KiB
ReStructuredText
Raw Normal View History

2021-07-30 19:29:14 +00:00
========================
django-changelist-inline
========================
Inline Changelists for Django
Overview
========
Django Admin comes with inlines_ which allows you to display forms to edit
related objects from the parent object's change form. While it's technically
possible to use this infrastructure to display list of related objects, it
gets hacky pretty fast.
Here's where *django-changelist-inline* comes into play. It allows you to embed
the standard list of objects as an inline on the parent object's change form.
Internally, it uses a subclass of ``ModelAdmin``, which means you can customize
the list as you'd normally do. Additionally, you can display links below the
list of objects.
Usage Example
=============
Let's assume you have a Django project with two models - ``Thing`` and
``RelatedThing`` and that you want to display list of ``RelatedThing`` objects
as an inline in ``Thing`` change form. The follwing snippet provides an example
of how to implement that using *django-changelist-inline*:
.. code-block:: python
# -*- coding: utf-8 -*-
from urllib.parse import urlencode
from django.contrib import admin
from django.urls import reverse
from django.utils.safestring import mark_safe
from django_changelist_inline import (
ChangelistInline,
ChangelistInlineAdmin,
ChangelistInlineModelAdmin,
)
from testing.models import RelatedThing, Thing
@admin.register(RelatedThing)
class RelatedThingModelAdmin(admin.ModelAdmin):
list_display = ('pk', 'name')
class RelatedThingChangelistInline(ChangelistInline):
model = RelatedThing
class ChangelistModelAdmin(ChangelistInlineModelAdmin):
list_display = ('name', 'format_actions')
list_display_links = None
list_per_page = 5
def get_queryset(self, request):
return RelatedThing.objects.filter(thing=self.parent_instance)
@mark_safe
def format_actions(self, obj=None):
if obj is None:
return self.empty_value_display
change_link_url = reverse(
'admin:{app_label}_{model_name}_change'.format(
app_label=RelatedThing._meta.app_label,
model_name=RelatedThing._meta.model_name,
),
args=[obj.pk],
)
return (
f'<a class="button" href="{change_link_url}">'
'Edit'
'</a>'
)
format_actions.short_description = 'Actions'
@property
def title(self):
return 'Linked Related Things'
@property
def no_results_message(self):
return 'No Related Things?'
def get_add_url(self, request):
result = super().get_add_url(request)
if result is not None:
return result + '?' + urlencode({
'thing': self.parent_instance.pk,
})
return result
def get_show_all_url(self, request):
result = super().get_show_all_url(request)
if result is not None:
return result + '?' + urlencode({
'thing': self.parent_instance.pk,
})
return result
def get_toolbar_links(self, request):
return (
'<a href="https://www.bthlabs.pl/">'
'BTHLabs'
'</a>'
)
@admin.register(Thing)
class ThingModelAdmin(ChangelistInlineAdmin):
inlines = (RelatedThingChangelistInline,)
API
===
``ChangelistInline`` objects
----------------------------
The ``ChangelistInline`` class is the center piece of the API. It's
designed to be used in a ``ModelAdmin``'s ``inlines``.
In order for it to work, you'll need to define the ``model`` property and
embed ``ChangelistModelAdmin`` class, which should be a subclass of
``ChangelistInlineModelAdmin``.
``ChangelistInlineModelAdmin`` objects
--------------------------------------
The ``ChangelistInlineModelAdmin`` is a customized ``ModelAdmin`` subclass
which provides sane defaults and additional functionality for inline
changelists.
**Changelist sanitization**
This subclass overrides the following attributes and methods of ``ModelAdmin``
to provide sane defaults:
* ``list_editable`` - set to empty tuple to disable editing of the list,
* ``list_filter`` - set to empty tuple to disable filtering of the list,
* ``search_fields`` - set to empty tuple to disable searching,
* ``date_hierarchy`` - set to ``None``,
* ``sortable_by`` - set to empty tuple to disable sorting,
* ``get_actions()`` - returns empty list to disable actions.
**Additional functionality**
To allow customization and to expose additional functionality,
``ChangelistInlineModelAdmin`` provides the following additional methods:
* ``title`` property - returns the model's *verbose name* by default.
* ``no_results_message`` property - returns text to display in place of the
table if no objects are fetched from the DB.
* ``get_add_url(request)`` - returns URL for the model's add form, if the
user has the add permission. Return ``None`` to hide the add link.
* ``get_show_all_url(request)`` - returns URL for the model's changelist, if
the user has the view permission. Return ``None`` to hide the show all link.
* ``get_toolbar_links(request)`` - returns ``None`` by default. Override this
to return string with additional ``<a/>`` elements to render in the toolbar.
The return value is marked safe in the template.
``ChangelistInlineAdmin`` objects
---------------------------------
The ``ChangelistInlineAdmin`` class is a base class for ``ModelAdmin``
subclasses that use inline changelists.
``ChangelistInlineAdminMixin``
------------------------------
A mixin class that is used to properly configure changelist inlines in the
parent ``ModelAdmin``. Overrides ``get_inlines(request, obj=None)`` and
``get_inline_instances(request, obj=None)`` methods.
If you can't use ``ChangelistInlineAdmin`` as you base class, you can use this
mixin to enable inline changelists:
.. code-block:: python
@admin.register(Thing)
class ThingModelAdmin(ChangelistInlineAdminMixin, MyBaseModelAdmin):
...
Author
------
*django-changelist-inline* is developed by `Tomek Wójcik`_.
License
-------
*django-changelist-inline* is licensed under the MIT License.
.. _inlines: https://docs.djangoproject.com/en/3.2/ref/contrib/admin/#inlinemodeladmin-objects
.. _Tomek Wójcik: https://www.bthlabs.pl/