repository·master·Indexed 21 days ago
https://github.com/jazzband/django-formtoolsA set of high-level abstractions for Django forms designed to handle form previews and multi-step form workflows. It includes FormPreview for automating a display-validation-confirmation sequence and a Form Wizard for splitting complex forms across multiple web pages using session or cookie storage.
django-formtools provides high-level abstractions for Django forms. It is primarily used for implementing:
Historically part of Django core (django.contrib.formtools), it is now a standalone package.
The formtools.wizard.views application allows you to split complex Django forms across multiple web pages. Instead of presenting a single, unwieldy form, you can break it into logical steps (e.g., core information on page one, secondary information on page two).
To manage state between these steps, the wizard maintains data in a backend (such as a session or database) so that full server-side processing is delayed until the final form in the sequence is submitted.
When rendering a wizard template, the wizard context object provides access to the current form and navigation helpers.
Required: You must include {{ wizard.management_form }} in your template for the wizard to function correctly.
wizard attributes:wizard.form: The current step's Form or BaseFormSet instance.wizard.management_form: The hidden management form required for tracking steps.wizard.steps: A helper object for navigation:wizard.steps.step1: Current step (1-based).wizard.steps.count: Total number of steps.wizard.steps.first: The first step.wizard.steps.last: The last step.wizard.steps.current: The current step.wizard.steps.next: The next step.wizard.steps.prev: The previous step.wizard.steps.index: The index of the current step.wizard.steps.all: A list of all steps.<!DOCTYPE html>
<html>
<body>
<p>Step {{ wizard.steps.step1 }} of {{ wizard.steps.count }}</p>
<form action="" method="post">
{% csrf_token %}
{{ wizard.management_form }}
{{ wizard.form }}
{% if wizard.steps.prev %}
<button name="wizard_goto_step" type="submit" value="{{ wizard.steps.prev }}">Previous</button>
{% endif %}
<input type="submit" value="Submit"/>
</form>
</body>
</html>The wizard follows a sequential lifecycle for each step:
The FormPreview application automates a multi-step form workflow:
done() hook with the validated data.Security: To prevent users from tampering with form parameters between the initial submission and the preview confirmation, FormPreview uses a shared-secret hash passed via hidden fields. If the hash comparison fails, the submission is rejected.
Limitation: FormPreview does not support file uploads.
To use FormPreview, follow these steps:
You must ensure Django can find the formtools templates. Choose one of two methods:
'formtools' to your INSTALLED_APPS setting. This works if your TEMPLATES setting uses the app_directories loader (the Django default).formtools/templates directory to the DIRS option in your TEMPLATES setting.Subclass FormPreview and implement the required done() method. This method is called after the user confirms the preview.
Map a URL to an instance of your FormPreview subclass, passing your form class as an argument.
# 1. Define the subclass
from django.http import HttpResponseRedirect
from formtools.preview import FormPreview
class SomeModelFormPreview(FormPreview):
def done(self, request, cleaned_data):
# Handle the validated data (e.g., save to DB)
# Then return a redirect to a success page
return HttpResponseRedirect('/form/success')
# 2. Register in urls.py
from django.urls import path
from myapp.forms import SomeModelForm
from myapp.preview import SomeModelFormPreview
urlpatterns = [
path('post/', SomeModelFormPreview(SomeModelForm)),
]To support django.forms.FileField in any step, you must define a file_storage attribute on your WizardView subclass. This attribute must be a django.core.files.storage.Storage subclass that temporarily stores uploaded files.
Warning: WizardView only removes these temporary files if the wizard completes successfully. You are responsible for cleaning up old temporary files.
from django.conf import settings
from django.core.files.storage import FileSystemStorage
class CustomWizardView(WizardView):
file_storage = FileSystemStorage(location=os.path.join(settings.MEDIA_ROOT, 'photos'))Install django-formtools using pip:
pip install django-formtoolsAlternatively, you can download the source distribution from PyPI, decompress it, and install it in editable mode:
pip install --editable .You can provide initial data for each step using the initial_dict argument when initializing the view. This should be a dictionary mapping step names (as strings) to dictionaries of initial values.
initial_dict can also be set as a class attribute on the WizardView subclass to avoid configuring it in urls.py.
initial = {
'0': {'subject': 'Hello', 'sender': 'user@example.com'},
'1': {'message': 'Hi there!'}
}
# Used when calling as_view()
# wiz = ContactWizard.as_view([ContactForm1, ContactForm2], initial_dict=initial)(request)If you are upgrading from the old django.contrib.formtools package to the standalone django-formtools package, you only need to update your import statements. The functionality remains identical as the code was copied directly from Django.
Example Migration:
Change:
from django.contrib.formtools.wizard.views import WizardViewTo:
from formtools.wizard.views import WizardView# Old import
from django.contrib.formtools.wizard.views import WizardView
# New import
from formtools.wizard.views import WizardViewIf you want every step of your wizard to have its own unique URL, use NamedUrlWizardView (or its session/cookie-backed variants NamedUrlSessionWizardView and NamedUrlCookieWizardView).
To implement this, you must:
NamedUrlWizardView.as_view instead of a list of classes, where each tuple is (step_name, form_class).urls.py to capture the step name in the URL pattern.url_name (required) and done_step_name (optional) to as_view.url_name refers to the name of the URL pattern in your urls.py that handles the steps.
# urls.py
from django.urls import path, re_path
from myapp.forms import ContactForm1, ContactForm2
from myapp.views import ContactWizard
# Define steps with names
named_contact_forms = (
('contactdata', ContactForm1),
('leavemessage', ContactForm2),
)
# Configure the view with url_name and done_step_name
contact_wizard = ContactWizard.as_view(
named_contact_forms,
url_name='contact_step',
done_step_name='finished'
)
urlpatterns = [
# The regex must capture the 'step' keyword argument
re_path(r'^contact/(?P<step>.+)/$', contact_wizard, name='contact_step'),
# The base URL for the wizard
path('contact/', contact_wizard, name='contact'),
]To implement a multi-step form wizard using django-formtools, follow these five steps:
django.forms.Form class for each step of the wizard.SessionWizardView (for server-side session storage) or CookieWizardView (for browser cookie storage). You must implement the done() method.formtools to your INSTALLED_APPS in Django settings.WizardView subclass using its .as_view() method, passing the list of form classes as an argument.from django import forms
from formtools.wizard.views import SessionWizardView
# 1. Define forms
class Step1Form(forms.Form):
name = forms.CharField()
class Step2Form(forms.Form):
email = forms.EmailField()
# 2. Create View
class MyWizard(SessionWizardView):
def done(self, form_list, **kwargs):
# Handle completed data
return render(self.request, 'done.html', {'data': [f.cleaned_data for f in form_list]})
# 5. URLconf
urlpatterns = [
path('wizard/', MyWizard.as_view([Step1Form, Step2Form])),
]