Metadata-Version: 2.4
Name: wagtail-forms
Version: 0.1.0
Summary: Reusable Wagtail flexible forms.
Author-email: Dazzy Mlv <23006212+DazzyMlv@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/dazzymlv/wagtail-forms
Project-URL: source, https://github.com/dazzymlv/wagtail-forms.git
Project-URL: changelog, https://github.com/DazzyMlv/wagtail-forms/blob/main/CHANGELOG.md
Project-URL: issues, https://github.com/dazzymlv/wagtail-forms/issues
Project-URL: documentation, https://github.com/dazzymlv/wagtail-forms/blob/main/README.md
Keywords: wagtail,forms,submissions,blocks,django
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Wagtail
Classifier: Framework :: Wagtail :: 6
Classifier: Framework :: Wagtail :: 7
Classifier: Framework :: tox
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Software Distribution
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: ua-parser[regex]>=1.0.1
Requires-Dist: wagtail>=6.4.0
Dynamic: license-file

# 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:

```bash
pip install wagtail-forms
```

Then add the app to `INSTALLED_APPS` in your Django settings:

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

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

```py
from django.urls import include, path

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

Run migrations:

```bash
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):

```py
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.

![Wagtail Admin Screenshot](https://raw.githubusercontent.com/dazzymlv/wagtail-forms/main/docs/screenshot-since-v0.1.0.png)

## 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

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

### Switch to a working branch

```bash
git switch -c feat/dev-setup
```

### Create a virtual environment

```bash
uv venv .venv
```

### Activate a virtual environment

PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
```

POSIX (bash / macOS / Linux):

```bash
source .venv/bin/activate
```

### Install package and dependencies

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

```bash
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:

```bash
python manage.py migrate
python manage.py createsuperuser
```

### Run the example site

Run with Django's development server:

```bash
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`):

```bash
# 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:

```bash
# 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:

```bash
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.
