Add admin

pfouque · pfouque · commit b40b3c088a19 · 2025-06-13T16:32:15.000+02:00
diff --git a/.gitignore b/.gitignore
@@ -130,3 +130,6 @@ dmypy.json
 
 # sqlite
 test.db
+*.sqlite3
+
+tests/testapp/migrations/
diff --git a/README.md b/README.md
@@ -405,6 +405,68 @@ ConcurrentTransitionMixin to cause a rollback of all the changes that
 have been executed in an inconsistent (out of sync) state, thus
 practically negating their effect.
 
+## Admin Integration
+
+1. Make sure `django_fsm` is in your `INSTALLED_APPS` settings:
+
+``` python
+INSTALLED_APPS = (
+    ...
+    'django_fsm',
+    ...
+)
+```
+
+NB: If you're migrating from [django-fsm-admin](https://github.com/gadventures/django-fsm-admin) (or any alternative), make sure it's not installed anymore to avoid installing the old django-fsm.
+
+
+2. In your admin.py file, use FSMAdminMixin to add behaviour to your ModelAdmin. FSMAdminMixin should be before ModelAdmin, the order is important.
+
+``` python
+from django_fsm.admin import FSMAdminMixin
+
+@admin.register(AdminBlogPost)
+class MyAdmin(FSMAdminMixin, admin.ModelAdmin):
+    fsm_field = ['my_fsm_field',]
+    ...
+```
+
+3. You can customize the label by adding ``custom={"label"="My awesome transition"}`` to the transition decorator
+
+``` python
+@transition(
+    field='state',
+    source=['startstate'],
+    target='finalstate',
+    custom={"label"=False},
+)
+def do_something(self, param):
+       ...
+```
+
+4. By adding ``custom={"admin"=False}`` to the transition decorator, one can disallow a transition to show up in the admin interface.
+
+``` python
+    @transition(
+       field='state',
+       source=['startstate'],
+       target='finalstate',
+       custom={"admin"=False},
+    )
+    def do_something(self, param):
+       # will not add a button "Do Something" to your admin model interface
+```
+
+By adding `FSM_ADMIN_FORCE_PERMIT = True` to your configuration settings (or `default_disallow_transition = False` to your admin), the above restriction becomes the default.
+Then one must explicitly allow that a transition method shows up in the admin interface.
+
+``` python
+@admin.register(AdminBlogPost)
+class MyAdmin(FSMAdminMixin, admin.ModelAdmin):
+    default_disallow_transition = False
+    ...
+```
+
 ## Drawing transitions
 
 Renders a graphical overview of your models states transitions
@@ -433,12 +495,6 @@ $ ./manage.py graph_transitions -o blog_transitions.png myapp.Blog
 
 ## Extensions
 
-You may also take a look at django-fsm-2-admin project containing a mixin
-and template tags to integrate django-fsm-2 state transitions into the
-django admin.
-
-<https://github.com/coral-li/django-fsm-2-admin>
-
 Transition logging support could be achieved with help of django-fsm-log
 package
 
diff --git a/django_fsm/admin.py b/django_fsm/admin.py
@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from django.conf import settings
+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 HttpResponseRedirect
+from django.utils.translation import gettext_lazy as _
+
+import django_fsm as fsm
+
+
+@dataclass
+class FSMObjectTransition:
+    fsm_field: str
+    block_label: str
+    available_transitions: list[fsm.Transition]
+
+
+class FSMAdminMixin(BaseModelAdmin):
+    change_form_template: str = "django_fsm/fsm_admin_change_form.html"
+
+    fsm_fields: list[str] = []
+    fsm_transition_success_msg = _("FSM transition '{transition_name}' succeeded.")
+    fsm_transition_error_msg = _("FSM transition '{transition_name}' failed: {error}.")
+    fsm_transition_not_allowed_msg = _("FSM transition '{transition_name}' is not allowed.")
+    fsm_transition_not_valid_msg = _("FSM transition '{transition_name}' is not a valid.")
+    fsm_context_key = "fsm_object_transitions"
+    fsm_post_param = "_fsm_transition_to"
+    default_disallow_transition = not getattr(settings, "FSM_ADMIN_FORCE_PERMIT", False)
+
+    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]:
+        read_only_fields = super().get_readonly_fields(request, obj)
+
+        for fsm_field_name in self.fsm_fields:
+            if fsm_field_name in read_only_fields:
+                continue
+            field = self.get_fsm_field_instance(fsm_field_name=fsm_field_name)
+            if field and getattr(field, "protected", False):
+                read_only_fields += (fsm_field_name,)
+
+        return read_only_fields
+
+    @staticmethod
+    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]:
+        fsm_object_transitions = []
+
+        for field_name in sorted(self.fsm_fields):
+            if func := getattr(obj, f"get_available_user_{field_name}_transitions"):
+                fsm_object_transitions.append(  # noqa: PERF401
+                    FSMObjectTransition(
+                        fsm_field=field_name,
+                        block_label=self.get_fsm_block_label(fsm_field_name=field_name),
+                        available_transitions=[
+                            t for t in func(user=request.user) if t.custom.get("admin", self.default_disallow_transition)
+                        ],
+                    )
+                )
+
+        return fsm_object_transitions
+
+    def change_view(
+        self,
+        request: HttpRequest,
+        object_id: str,
+        form_url: str = "",
+        extra_context: dict[str, Any] | None = None,
+    ) -> HttpResponse:
+        _context = extra_context or {}
+        _context[self.fsm_context_key] = self.get_fsm_object_transitions(
+            request=request,
+            obj=self.get_object(request=request, object_id=object_id),
+        )
+
+        return super().change_view(
+            request=request,
+            object_id=object_id,
+            form_url=form_url,
+            extra_context=_context,
+        )
+
+    def get_fsm_redirect_url(self, request: HttpRequest, obj: Any) -> str:
+        return request.path
+
+    def get_fsm_response(self, request: HttpRequest, obj: Any) -> HttpResponse:
+        redirect_url = self.get_fsm_redirect_url(request=request, obj=obj)
+        redirect_url = add_preserved_filters(
+            context={
+                "preserved_filters": self.get_preserved_filters(request),
+                "opts": self.model._meta,
+            },
+            url=redirect_url,
+        )
+        return HttpResponseRedirect(redirect_to=redirect_url)
+
+    def response_change(self, request: HttpRequest, obj: Any) -> HttpResponse:
+        if self.fsm_post_param in request.POST:
+            try:
+                transition_name = request.POST[self.fsm_post_param]
+                transition_func = getattr(obj, transition_name)
+            except AttributeError:
+                self.message_user(
+                    request=request,
+                    message=self.fsm_transition_not_valid_msg.format(
+                        transition_name=transition_name,
+                    ),
+                    level=messages.ERROR,
+                )
+                return self.get_fsm_response(
+                    request=request,
+                    obj=obj,
+                )
+
+            try:
+                transition_func()
+            except fsm.TransitionNotAllowed:
+                self.message_user(
+                    request=request,
+                    message=self.fsm_transition_not_allowed_msg.format(
+                        transition_name=transition_name,
+                    ),
+                    level=messages.ERROR,
+                )
+            except fsm.ConcurrentTransition as err:
+                self.message_user(
+                    request=request,
+                    message=self.fsm_transition_error_msg.format(transition_name=transition_name, error=str(err)),
+                    level=messages.ERROR,
+                )
+            else:
+                obj.save()
+                self.message_user(
+                    request=request,
+                    message=self.fsm_transition_success_msg.format(
+                        transition_name=transition_name,
+                    ),
+                    level=messages.INFO,
+                )
+
+            return self.get_fsm_response(
+                request=request,
+                obj=obj,
+            )
+
+        return super().response_change(request=request, obj=obj)
diff --git a/django_fsm/templates/django_fsm/fsm_admin_change_form.html b/django_fsm/templates/django_fsm/fsm_admin_change_form.html
@@ -0,0 +1,15 @@
+{% extends 'admin/change_form.html' %}
+
+{% block submit_buttons_bottom %}
+
+  {% for fsm_object_transition in fsm_object_transitions %}
+      <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">
+        {% endfor %}
+      </div>
+  {% endfor %}
+
+  {{ block.super }}
+{% endblock %}
diff --git a/tests/testapp/admin.py b/tests/testapp/admin.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from django.contrib import admin
+
+from django_fsm.admin import FSMAdminMixin
+
+from .models import AdminBlogPost
+
+
+@admin.register(AdminBlogPost)
+class AdminBlogPostAdmin(FSMAdminMixin, admin.ModelAdmin):
+    list_display = (
+        "id",
+        "title",
+        "state",
+        "step",
+    )
+
+    fsm_fields = [
+        "state",
+        "step",
+    ]
diff --git a/tests/testapp/models.py b/tests/testapp/models.py
@@ -140,3 +140,107 @@ def steal(self):
     @transition(field=state, source="*", target="moderated")
     def moderate(self):
         pass
+
+
+class AdminBlogPostState(models.TextChoices):
+    CREATED = "created", "Created"
+    REVIEWED = "reviewed", "Reviewed"
+    PUBLISHED = "published", "Published"
+    HIDDEN = "hidden", "Hidden"
+
+
+class AdminBlogPostStep(models.TextChoices):
+    STEP_1 = "step1", "Step one"
+    STEP_2 = "step2", "Step two"
+    STEP_3 = "step3", "Step three"
+
+
+class AdminBlogPost(models.Model):
+    title = models.CharField(max_length=50)
+
+    state = FSMField(
+        choices=AdminBlogPostState.choices,
+        default=AdminBlogPostState.CREATED,
+        protected=True,
+    )
+
+    step = FSMField(
+        choices=AdminBlogPostStep.choices,
+        default=AdminBlogPostStep.STEP_1,
+        protected=False,
+    )
+
+    # state transitions
+
+    @transition(
+        field=state,
+        source="*",
+        target=AdminBlogPostState.HIDDEN,
+        custom={
+            "admin": False,
+        },
+    )
+    def secret_transition(self):
+        pass
+
+    @transition(
+        field=state,
+        source=[AdminBlogPostState.CREATED],
+        target=AdminBlogPostState.REVIEWED,
+    )
+    def moderate(self):
+        pass
+
+    @transition(
+        field=state,
+        source=[
+            AdminBlogPostState.REVIEWED,
+            AdminBlogPostState.HIDDEN,
+        ],
+        target=AdminBlogPostState.PUBLISHED,
+    )
+    def publish(self):
+        pass
+
+    @transition(
+        field=state,
+        source=[
+            AdminBlogPostState.REVIEWED,
+            AdminBlogPostState.PUBLISHED,
+        ],
+        target=AdminBlogPostState.HIDDEN,
+    )
+    def hide(self):
+        pass
+
+    # step transitions
+
+    @transition(
+        field=step,
+        source=[AdminBlogPostStep.STEP_1],
+        target=AdminBlogPostStep.STEP_2,
+        custom={
+            "label": "Go to Step 2",
+        },
+    )
+    def step_two(self):
+        pass
+
+    @transition(
+        field=step,
+        source=[AdminBlogPostStep.STEP_2],
+        target=AdminBlogPostStep.STEP_3,
+    )
+    def step_three(self):
+        pass
+
+    @transition(
+        field=step,
+        source=[
+            AdminBlogPostStep.STEP_2,
+            AdminBlogPostStep.STEP_3,
+        ],
+        target=AdminBlogPostStep.STEP_1,
+    )
+    def step_reset(self):
+        pass
diff --git a/tests/testapp/tests/test_admin.py b/tests/testapp/tests/test_admin.py
