Wagtail Forms

Lightweight utilities to collect and manage ad-hoc Django/Wagtail form submissions without requiring a form Page type. Provides a small model layer, admin views for browsing submissions, and a helpful Form base class with a submit() helper.

Features

• Store arbitrary Django form submissions in a FormSubmission model
• Small Form model to group submissions by logical label
• wagtail_forms.forms.Form base class with a submit(request=...) convenience method
• Wagtail admin integrations for listing, inspecting, exporting and deleting submissions
• Templates for simple submission viewing and index pages (overrideable)

Requirements

• Python 3.11+
• Django (compatible release for your project)
• Wagtail (compatible release for your project)
• django.contrib.humanize must be added to INSTALLED_APPS in your Django settings (required by package templates)

This project's pyproject.toml specifies requires-python = ">=3.11" — pick Django/Wagtail versions that match your site.

Installation

Install from source (editable) for development:

pip install wagtail-forms

Then add the app to INSTALLED_APPS in your Django settings:

INSTALLED_APPS = [
 # ...
 'wagtail_forms',
 'django.contrib.humanize',
]

Include the URL patterns where appropriate (example for a site urls.py):

from django.urls import include, path

urlpatterns = [
 # ...
 path('forms/', include('wagtail_forms.urls')),
]

Run migrations:

python manage.py migrate

Quickstart

Create a Django form class that subclasses wagtail_forms.forms.Form. When the form is valid call its submit() method with the request to persist a submission and attach metadata (IP, user agent, referer, user):

from django import forms
from wagtail_forms.forms import Form as WagtailForm

class ContactForm(WagtailForm):
 name = forms.CharField(max_length=255)
 email = forms.EmailField()
 message = forms.CharField(widget=forms.Textarea)

# In your view:
def contact_view(request):
 form = ContactForm(request.POST or None)
 if request.method == 'POST' and form.is_valid():
  fm = form.submit(request=request)
  # `fm` is or represents the stored `wagtail_forms.models.Form` instance
  # you can redirect or render a thanks page

The submit() helper will create or get a Form record using the class name as the label (or _label if set on the form class) and call the model's processing logic to create a FormSubmission row.

Admin & Inspecting Submissions

The project exposes models Form and FormSubmission. In the Wagtail admin you get list views and an inspect view for individual submissions. FormSubmission includes helpful properties for:

• form_data_humanized — a cleaned representation of stored form data
• form_data_json — JSON representation of the submission
• parsed user-agent and derived browser/device
• location helper that attempts to resolve an IP to a city/country (when available)

There are also views and URL helpers to export submissions and delete them in bulk.

Templates

Ship templates live under wagtail_forms/templates/wtforms/. You can override these in your project templates directory by providing templates with the same paths. Notable templates:

• wtforms/index.html — index/listing view
• wtforms/submissions/view.html — single submission inspect view

Development

This project includes an example Wagtail project under the example/ directory you can use to test and develop the library locally.

Recommended steps (PowerShell / cross-platform commands shown):

Clone the repository

git clone git@github.com:DazzyMlv/wagtail-forms.git
cd wagtail-forms

Switch to a working branch

git switch -c feat/dev-setup

Create a virtual environment

uv venv .venv

Activate a virtual environment

PowerShell:

.\.venv\Scripts\Activate.ps1

POSIX (bash / macOS / Linux):

source .venv/bin/activate

Install package and dependencies

Install the project in editable mode and any example requirements if present:

uv sync --group dev --group test
uv add --dev --editable . # OR pip install -e .
pre-commit install

Initialize the example project

Run migrations and create a superuser:

python manage.py migrate
python manage.py createsuperuser

Run the example site

Run with Django's development server:

python manage.py runserver # OR python manage.py runserver_plus

Or, if you prefer an ASGI server and the example exposes an ASGI app, you can run with uvicorn (install with pip install uvicorn):

# example: uvicorn example_project.asgi:application --reload --port 8000
uvicorn example.asgi:application --reload

Run tests and linters

If you add tests or linters, run them:

# run project tests (if present)
python -m pytest

# run linters (if configured)
flake8 src tests

Commit and push your changes to GitHub

Make small, focused commits. Example workflow:

pre-commit run --all-files
git add -A
git commit -m "core: improve development docs and example setup"
git push -u origin feat/dev-setup
# Open a PR on GitHub to merge into develop/main

Notes

• The example/ folder is intended to make it quick to smoke-test the library inside a minimal Wagtail project. Inspect its README or files for any example-specific setup steps.
• Use the editable install (pip install -e . OR uv add --dev --editable .) so changes to src/wagtail_forms are picked up by the running example without reinstalling.
• If you prefer Docker for development, you can add a small docker-compose setup that builds an image from this repo and runs the example project; that is not included by default.

Contributing

Contributions are welcome. Please open an issue to discuss larger changes before sending a pull request. Keep changes focused and include tests where appropriate.

License

This project is released under the MIT License. See LICENSE for details.

Contact / Support

Open issues on the repository for bugs or feature requests.