Add admin forms support

Author: pfouque

django_fsm/admin.py

@@ -1,21 +1,32 @@
 from __future__ import annotations
 
+import typing
 from dataclasses import dataclass
 from functools import partial
 from typing import Any
 
 from django.conf import settings
+from django.contrib import admin
 from django.contrib import messages
 from django.contrib.admin.options import BaseModelAdmin
 from django.contrib.admin.templatetags.admin_urls import add_preserved_filters
 from django.core.exceptions import FieldDoesNotExist
 from django.http import HttpRequest
 from django.http import HttpResponse
+from django.http import HttpResponseBadRequest
 from django.http import HttpResponseRedirect
+from django.shortcuts import redirect
+from django.shortcuts import render
+from django.urls import path
+from django.urls import reverse
+from django.utils.module_loading import import_string
 from django.utils.translation import gettext_lazy as _
 
 import django_fsm as fsm
 
+if typing.TYPE_CHECKING:
+    from django.forms import Form
+
 try:
     import django_fsm_log  # noqa: F401
 except ModuleNotFoundError:
@@ -24,6 +35,8 @@
     FSM_LOG_ENABLED = True
 
 
+
+
 @dataclass
 class FSMObjectTransition:
     fsm_field: str
@@ -42,14 +55,26 @@ class FSMAdminMixin(BaseModelAdmin):
     fsm_context_key = "fsm_object_transitions"
     fsm_post_param = "_fsm_transition_to"
     default_disallow_transition = not getattr(settings, "FSM_ADMIN_FORCE_PERMIT", False)
+    fsm_transition_form_template = "django_fsm/fsm_admin_transition_form.html"
+
+    def get_urls(self):
+        meta = self.model._meta
+        return [
+            path(
+                "<path:object_id>/transition/<str:transition_name>/",
+                self.admin_site.admin_view(self.fsm_transition_view),
+                name=f"{meta.app_label}_{meta.model_name}_transition",
+            ),
+            *super().get_urls(),
+        ]
 
     def get_fsm_field_instance(self, fsm_field_name: str) -> fsm.FSMField | None:
         try:
             return self.model._meta.get_field(fsm_field_name)
         except FieldDoesNotExist:
             return None
 
-    def get_readonly_fields(self, request: HttpRequest, obj: Any = None) -> tuple[str]:
+    def get_readonly_fields(self, request: HttpRequest, obj: typing.Any = None) -> tuple[str]:
         read_only_fields = super().get_readonly_fields(request, obj)
 
         for fsm_field_name in self.fsm_fields:
@@ -65,7 +90,7 @@ def get_readonly_fields(self, request: HttpRequest, obj: Any = None) -> tuple[st
     def get_fsm_block_label(fsm_field_name: str) -> str:
         return f"Transition ({fsm_field_name})"
 
-    def get_fsm_object_transitions(self, request: HttpRequest, obj: Any) -> list[FSMObjectTransition]:
+    def get_fsm_object_transitions(self, request: HttpRequest, obj: typing.Any) -> list[FSMObjectTransition]:
         fsm_object_transitions = []
 
         for field_name in sorted(self.fsm_fields):
@@ -82,12 +107,18 @@ def get_fsm_object_transitions(self, request: HttpRequest, obj: Any) -> list[FSM
 
         return fsm_object_transitions
 
+    def get_fsm_transition_form(self, transition: fsm.Transition) -> Form | None:
+        form = transition.custom.get("form")
+        if isinstance(form, str):
+            form = import_string(form)
+        return form
+
     def change_view(
         self,
         request: HttpRequest,
         object_id: str,
         form_url: str = "",
-        extra_context: dict[str, Any] | None = None,
+        extra_context: dict[str, typing.Any] | None = None,
     ) -> HttpResponse:
         _context = extra_context or {}
         _context[self.fsm_context_key] = self.get_fsm_object_transitions(
@@ -102,10 +133,10 @@ def change_view(
             extra_context=_context,
         )
 
-    def get_fsm_redirect_url(self, request: HttpRequest, obj: Any) -> str:
+    def get_fsm_redirect_url(self, request: HttpRequest, obj: typing.Any) -> str:
         return request.path
 
-    def get_fsm_response(self, request: HttpRequest, obj: Any) -> HttpResponse:
+    def get_fsm_response(self, request: HttpRequest, obj: typing.Any) -> HttpResponse:
         redirect_url = self.get_fsm_redirect_url(request=request, obj=obj)
         redirect_url = add_preserved_filters(
             context={
@@ -116,7 +147,7 @@ def get_fsm_response(self, request: HttpRequest, obj: Any) -> HttpResponse:
         )
         return HttpResponseRedirect(redirect_to=redirect_url)
 
-    def response_change(self, request: HttpRequest, obj: Any) -> HttpResponse:
+    def response_change(self, request: HttpRequest, obj: typing.Any) -> HttpResponse:
         if self.fsm_post_param in request.POST:
             try:
                 transition_name = request.POST[self.fsm_post_param]
@@ -134,6 +165,20 @@ def response_change(self, request: HttpRequest, obj: Any) -> HttpResponse:
                     obj=obj,
                 )
 
+            # NOTE: if a form is defined on the transition, we redirect to the form view
+            if transition_func._django_fsm.get_transition(
+                source=transition_func._django_fsm.field.get_state(obj),
+            ).custom.get("form"):
+                return redirect(
+                    reverse(
+                        f"admin:{self.model._meta.app_label}_{self.model._meta.model_name}_transition",
+                        kwargs={
+                            "object_id": obj.pk,
+                            "transition_name": transition_name,
+                        },
+                    )
+                )
+
             try:
                 if FSM_LOG_ENABLED:
                     for fn in [
@@ -179,3 +224,69 @@ def response_change(self, request: HttpRequest, obj: Any) -> HttpResponse:
             )
 
         return super().response_change(request=request, obj=obj)
+
+    @staticmethod
+    def _get_transition_title(transition):
+        return getattr(transition.custom, "label", None) or transition.name
+
+    def fsm_transition_view(self, request, *args, **kwargs):
+        transition_name = kwargs["transition_name"]
+        obj = self.get_object(request, kwargs["object_id"])
+
+        transition_method = getattr(obj, transition_name)
+        if not hasattr(transition_method, "_django_fsm"):
+            return HttpResponseBadRequest(f"{transition_name} is not a transition method")
+
+        transitions = transition_method._django_fsm.transitions
+        if isinstance(transitions, dict):
+            transitions = list(transitions.values())
+        transition = transitions[0]
+
+        if TransitionForm := self.get_fsm_transition_form(transition):
+            if request.method == "POST":
+                transition_form = TransitionForm(data=request.POST, instance=obj)
+                if transition_form.is_valid():
+                    transition_method(**transition_form.cleaned_data)
+                    obj.save()
+                else:
+                    return render(
+                        request,
+                        self.fsm_transition_form_template,
+                        context=admin.site.each_context(request)
+                        | {
+                            "opts": self.model._meta,
+                            "original": obj,
+                            "transition": transition,
+                            "transition_form": transition_form,
+                        },
+                    )
+            else:
+                transition_form = TransitionForm(instance=obj)
+                return render(
+                    request,
+                    self.fsm_transition_form_template,
+                    context=admin.site.each_context(request)
+                    | {
+                        "opts": self.model._meta,
+                        "original": obj,
+                        "transition": transition,
+                        "transition_form": transition_form,
+                    },
+                )
+        else:
+            try:
+                transition_method()
+            except fsm.TransitionNotAllowed:
+                self.message_user(
+                    request,
+                    _("Transition %(transition)s is not allowed") % {"transition": self._get_transition_title(transition)},
+                    messages.ERROR,
+                )
+            else:
+                obj.save()
+                self.message_user(
+                    request,
+                    _("Transition %(transition)s applied") % {"transition": self._get_transition_title(transition)},
+                    messages.SUCCESS,
+                )
+        return redirect(f"admin:{self.model._meta.app_label}_{self.model._meta.model_name}_change", object_id=obj.id)

django_fsm/templates/django_fsm/fsm_admin_change_form.html

@@ -6,7 +6,9 @@
       <div class="submit-row">
         <label>{{ fsm_object_transition.block_label }}</label>
         {% for transition in fsm_object_transition.available_transitions %}
-          <input type="submit" value="{{ transition.custom.label|default:transition.name }}" name="_fsm_transition_to">
+        <button type="submit" class="button" name="_fsm_transition_to" value="{{ transition.name }}">
+          {{ transition.custom.label|default:transition.name }}
+        </button>
         {% endfor %}
       </div>
   {% endfor %}

django_fsm/templates/django_fsm/fsm_admin_transition_form.html

@@ -0,0 +1,24 @@
+{% extends 'admin/change_form.html' %}
+
+{% load i18n admin_urls static admin_modify %}
+
+{% block breadcrumbs %}
+<div class="breadcrumbs">
+<a href="{% url 'admin:index' %}">{% translate 'Home' %}</a>
+&rsaquo; <a href="{% url 'admin:app_list' app_label=opts.app_label %}">{{ opts.app_config.verbose_name }}</a>
+&rsaquo; <a href="{% url opts|admin_urlname:'changelist' %}">{{ opts.verbose_name_plural|capfirst }}</a>
+&rsaquo; <a href="{% url opts|admin_urlname:'change' object_id=original.pk %}">{{ original|truncatewords:"18" }}</a>
+&rsaquo; {{ transition.custom.short_description|default:transition.name }}
+</div>
+{% endblock %}
+
+{% block content %}
+<h1>{{ transition.custom.short_description|default:transition.name }}</h1>
+
+<form method="post">
+    {% csrf_token %}
+    {{ transition_form.as_p }}
+    <input type="submit" value="{% translate 'Apply' %}">
+</form>
+
+{% endblock %}

pyproject.toml

@@ -64,6 +64,7 @@ extend-ignore = [
     "COM812",  # This rule may cause conflicts when used with the formatter
     "D",  # pydocstyle
     "DOC",  # pydoclint
+    "N806", # Variable in function should be lowercase
     "B",
     "PTH",
     "ANN",  # Missing type annotation

tests/testapp/admin_forms.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from django import forms
+
+from .models import AdminBlogPost
+
+
+class AdminBlogPostRenameForm(forms.ModelForm):
+    """
+    This form is used to test the admin form renaming functionality.
+    It should not be used in production.
+    """
+
+    class Meta:
+        model = AdminBlogPost
+        fields = ["title"]  # Do not try to update the state field, especially if it's "protected" in the model.

tests/testapp/models.py

@@ -279,7 +279,8 @@ class AdminBlogPost(models.Model):
         protected=False,
     )
 
-    # state transitions
+    def __str__(self):
+        return f"{self.title} ({self.state})"
 
     @fsm_log_by
     @fsm_log_description
@@ -330,6 +331,18 @@ def publish(self, by=None, description=None):
     def hide(self, by=None, description=None):
         pass
 
+    @transition(
+        field=state,
+        source="*",
+        target=AdminBlogPostState.CREATED,
+        custom={
+            "label": "Rename *",
+            "form": "tests.testapp.admin_forms.AdminBlogPostRenameForm",
+        },
+    )
+    def complex_transition(self, new_title: str):
+        self.title = new_title
+
     # step transitions
 
     @fsm_log_by