Added Changes column to admin history page

This lists the changes between each historical record of the object.

Effort has been made to make it easy for library users to override most
parts of this, and to let them customize only the details they want to
without having to copy or replace our implementation.
An overview of how to override it has been added to `admin.rst`.

Most of the code was added to `template_utils.py`, to avoid cluttering
`SimpleHistoryAdmin`.

Also updated the Norwegian Bokmål translations,
and updated all the docs screenshots, to make them have Django 5.0's UI
and to showcase the new column.

Co-authored-by: Gur Raunaq Singh <[email protected]>
Co-authored-by: Tim Schilling <[email protected]>

Author: 3 people

CHANGES.rst

@@ -22,6 +22,9 @@ Unreleased
   lists are sorted by the related object. This should help prevent flaky tests. (gh-1128)
 - ``diff_against()`` has a new keyword argument, ``foreign_keys_are_objs``;
   see usage in the docs under "History Diffing" (gh-1128)
+- Added a "Changes" column to ``SimpleHistoryAdmin``'s object history table, listing
+  the changes between each historical record of the object; see the docs under
+  "Customizing the History Admin Templates" for overriding its template context (gh-1128)
 
 3.5.0 (2024-02-19)
 ------------------

docs/admin.rst

@@ -84,7 +84,26 @@ you can override the following attributes with the names of your own templates:
   historical record, which also allows you to revert the object to a previous version.
 
 If you'd like to only customize certain parts of the mentioned templates, look for
-``block`` template tags in the source code that you can override.
+``block`` template tags in the source code that you can override - like the
+``history_delta_changes`` block in ``simple_history/object_history_list.html``,
+which lists the changes made between each historical record.
+
+Customizing Context
+^^^^^^^^^^^^^^^^^^^
+
+You can also customize the template context by overriding the following methods:
+
+- ``render_history_view()``: Called by both ``history_view()`` and
+  ``history_form_view()`` before the templates are rendered. Customize the context by
+  changing the ``context`` parameter.
+- ``history_view()``: Returns a rendered ``object_history_template``.
+  Inject context by calling the super method with the ``extra_context`` argument.
+- ``get_historical_record_context_helper()``: Returns an instance of
+  ``simple_history.template_utils.HistoricalRecordContextHelper`` that's used to format
+  some template context for each historical record displayed through ``history_view()``.
+  Customize the context by extending the mentioned class and overriding its methods.
+- ``history_form_view()``: Returns a rendered ``object_history_form_template``.
+  Inject context by calling the super method with the ``extra_context`` argument.
 
 
 Disabling the option to revert an object

docs/screens/10_revert_disabled.png

@@ -16,7 +16,9 @@
 from django.utils.text import capfirst
 from django.utils.translation import gettext as _
 
-from .manager import HistoryManager
+from .manager import HistoricalQuerySet, HistoryManager
+from .models import HistoricalChanges
+from .template_utils import HistoricalRecordContextHelper
 from .utils import get_history_manager_for_model, get_history_model_for_model
 
 SIMPLE_HISTORY_EDIT = getattr(settings, "SIMPLE_HISTORY_EDIT", False)
@@ -76,14 +78,16 @@ def history_view(self, request, object_id, extra_context=None):
                 for record in historical_records:
                     setattr(record, history_list_entry, value_for_entry(record))
 
+        self.set_history_delta_changes(request, historical_records)
+
         content_type = self.content_type_model_cls.objects.get_for_model(
             get_user_model()
         )
-
         admin_user_view = "admin:{}_{}_change".format(
             content_type.app_label,
             content_type.model,
         )
+
         context = {
             "title": self.history_view_title(request, obj),
             "object_history_list_template": self.object_history_list_template,
@@ -117,10 +121,12 @@ def get_history_queryset(
         :param pk_name: The name of the original model's primary key field.
         :param object_id: The primary key of the object whose history is listed.
         """
-        qs = history_manager.filter(**{pk_name: object_id})
+        qs: HistoricalQuerySet = history_manager.filter(**{pk_name: object_id})
         if not isinstance(history_manager.model.history_user, property):
             # Only select_related when history_user is a ForeignKey (not a property)
             qs = qs.select_related("history_user")
+        # Prefetch related objects to reduce the number of DB queries when diffing
+        qs = qs._select_related_history_tracked_objs()
         return qs
 
     def get_history_list_display(self, request) -> Sequence[str]:
@@ -131,6 +137,44 @@ def get_history_list_display(self, request) -> Sequence[str]:
         """
         return self.history_list_display
 
+    def get_historical_record_context_helper(
+        self, request, historical_record: HistoricalChanges
+    ) -> HistoricalRecordContextHelper:
+        """
+        Return an instance of ``HistoricalRecordContextHelper`` for formatting
+        the template context for ``historical_record``.
+        """
+        return HistoricalRecordContextHelper(self.model, historical_record)
+
+    def set_history_delta_changes(
+        self,
+        request,
+        historical_records: Sequence[HistoricalChanges],
+        foreign_keys_are_objs=True,
+    ):
+        """
+        Add a ``history_delta_changes`` attribute to all historical records
+        except the first (oldest) one.
+
+        :param request:
+        :param historical_records:
+        :param foreign_keys_are_objs: Passed to ``diff_against()`` when calculating
+               the deltas; see its docstring for details.
+        """
+        previous = None
+        for current in historical_records:
+            if previous is None:
+                previous = current
+                continue
+            # Related objects should have been prefetched in `get_history_queryset()`
+            delta = previous.diff_against(
+                current, foreign_keys_are_objs=foreign_keys_are_objs
+            )
+            helper = self.get_historical_record_context_helper(request, previous)
+            previous.history_delta_changes = helper.context_for_delta_changes(delta)
+
+            previous = current
+
     def history_view_title(self, request, obj):
         if self.revert_disabled(request, obj) and not SIMPLE_HISTORY_EDIT:
             return _("View history: %s") % force_str(obj)