Frontend Viewset

Viewflow’s FSM can be integrated with the frontend viewset for a streamlined user experience. This allows you to expose state transitions as user actions in your application’s interface.

Basic Integration

To integrate your FSM with a viewset, use the FlowViewsMixin provided by Viewflow:

# viewset.py

from viewflow.fsm import FlowViewsMixin
from viewflow.views import ModelViewSet
from .flow import ReportFlow
from .models import Report

class ReportViewSet(FlowViewsMixin, ModelViewSet):
    model = Report
    flow_class = ReportFlow

    # Standard viewset configuration
    queryset = Report.objects.all()
    list_display = ['id', 'text', 'state_field']
    detail_actions = ['approve', 'reject', 'publish']

This integration automatically adds transition actions to your detail views and handles permission checking.

Custom Transition Views

For transitions that require user input, you can define custom transition forms:

# forms.py

from django import forms
from .models import Report

class ApproveForm(forms.ModelForm):
    comment = forms.CharField(widget=forms.Textarea)

    class Meta:
        model = Report
        fields = []  # The state field is handled by the flow

# viewset.py

class ReportViewSet(FlowViewsMixin, ModelViewSet):
    # ...previous configuration...

    def get_transition_form_class(self, transition_name):
        if transition_name == 'approve':
            return ApproveForm
        return super().get_transition_form_class(transition_name)

    def perform_transition(self, instance, transition_name, form=None):
        flow = self.get_flow_instance(instance)
        if transition_name == 'approve' and form is not None:
            # Store the comment before transition
            instance.approval_comment = form.cleaned_data['comment']

        # Perform the transition
        transition = getattr(flow, transition_name)
        transition()

Template Customization

The viewset uses a standard template structure for transitions:

• viewflow/fsm/{model_name}/{transition_name}.html - Specific transition template
• viewflow/fsm/{model_name}/transition_form.html - Model-specific transition form
• viewflow/fsm/transition_form.html - Generic transition form

You can override these templates to customize the user interface:

<!-- templates/viewflow/fsm/report/approve.html -->
{% extends "viewflow/fsm/transition_form.html" %}

{% block transition_title %}
    Approve Report #{{ object.pk }}
{% endblock %}

{% block transition_subtitle %}
    Please review the report carefully before approval.
{% endblock %}

State Visualization

The viewset also provides a visual representation of the state machine. You can access this at:

# urls.py

from django.urls import path, include
from .viewset import ReportViewSet

urlpatterns = [
    path('reports/', include(ReportViewSet().urls)),
    # This will create a URL pattern for /reports/chart/ that displays the FSM graph
]

This visualization helps users understand the possible state transitions and the current state of the instance.