mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-23 09:11:09 -05:00
Add standardized HTMX conventions, interaction patterns, and migration guide for ThrillWiki UX
This commit is contained in:
pacnpal
225
backend/templates/forms/README.md
Normal file
225
backend/templates/forms/README.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Form Templates
|
||||
|
||||
This directory contains form-related templates for ThrillWiki.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
forms/
|
||||
├── partials/ # Individual form components
|
||||
│ ├── form_field.html # Complete form field
|
||||
│ ├── field_error.html # Error messages
|
||||
│ ├── field_success.html # Success indicator
|
||||
│ └── form_actions.html # Submit/cancel buttons
|
||||
├── layouts/ # Form layout templates
|
||||
│ ├── stacked.html # Vertical layout
|
||||
│ ├── inline.html # Horizontal layout
|
||||
│ └── grid.html # Multi-column grid
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Form Layouts
|
||||
|
||||
### Stacked Layout (Default)
|
||||
|
||||
Vertical layout with full-width fields:
|
||||
|
||||
```django
|
||||
{% include 'forms/layouts/stacked.html' with form=form %}
|
||||
|
||||
{# With options #}
|
||||
{% include 'forms/layouts/stacked.html' with
|
||||
form=form
|
||||
submit_text='Save Changes'
|
||||
show_cancel=True
|
||||
cancel_url='/parks/'
|
||||
%}
|
||||
```
|
||||
|
||||
### Inline Layout
|
||||
|
||||
Horizontal layout with labels beside inputs:
|
||||
|
||||
```django
|
||||
{% include 'forms/layouts/inline.html' with form=form %}
|
||||
|
||||
{# Custom label width #}
|
||||
{% include 'forms/layouts/inline.html' with form=form label_width='w-1/4' %}
|
||||
```
|
||||
|
||||
### Grid Layout
|
||||
|
||||
Multi-column responsive grid:
|
||||
|
||||
```django
|
||||
{# 2-column grid #}
|
||||
{% include 'forms/layouts/grid.html' with form=form cols=2 %}
|
||||
|
||||
{# 3-column grid #}
|
||||
{% include 'forms/layouts/grid.html' with form=form cols=3 %}
|
||||
|
||||
{# Full-width description field #}
|
||||
{% include 'forms/layouts/grid.html' with form=form cols=2 full_width='description' %}
|
||||
```
|
||||
|
||||
## Layout Parameters
|
||||
|
||||
| Parameter | Description | Default |
|
||||
|-----------|-------------|---------|
|
||||
| `form` | Django form object | Required |
|
||||
| `exclude` | Comma-separated fields to exclude | None |
|
||||
| `fields` | Comma-separated fields to include | All |
|
||||
| `show_help` | Show help text | True |
|
||||
| `show_required` | Show required indicator | True |
|
||||
| `submit_text` | Submit button text | 'Submit' |
|
||||
| `submit_class` | Submit button CSS class | 'btn-primary' |
|
||||
| `show_cancel` | Show cancel button | False |
|
||||
| `cancel_url` | URL for cancel link | None |
|
||||
| `cancel_text` | Cancel button text | 'Cancel' |
|
||||
| `show_actions` | Show action buttons | True |
|
||||
|
||||
## Individual Components
|
||||
|
||||
### Form Field
|
||||
|
||||
Complete field with label, input, help, and errors:
|
||||
|
||||
```django
|
||||
{% include 'forms/partials/form_field.html' with field=form.email %}
|
||||
|
||||
{# Custom label #}
|
||||
{% include 'forms/partials/form_field.html' with field=form.email label='Your Email' %}
|
||||
|
||||
{# Without label #}
|
||||
{% include 'forms/partials/form_field.html' with field=form.search show_label=False %}
|
||||
|
||||
{# Inline layout #}
|
||||
{% include 'forms/partials/form_field.html' with field=form.email layout='inline' %}
|
||||
|
||||
{# HTMX validation #}
|
||||
{% include 'forms/partials/form_field.html' with
|
||||
field=form.username
|
||||
hx_validate=True
|
||||
hx_validate_url='/api/validate/username/'
|
||||
%}
|
||||
```
|
||||
|
||||
### Field Error
|
||||
|
||||
Error message display:
|
||||
|
||||
```django
|
||||
{% include 'forms/partials/field_error.html' with errors=field.errors %}
|
||||
|
||||
{# Without icon #}
|
||||
{% include 'forms/partials/field_error.html' with errors=field.errors show_icon=False %}
|
||||
|
||||
{# Different size #}
|
||||
{% include 'forms/partials/field_error.html' with errors=field.errors size='md' %}
|
||||
```
|
||||
|
||||
### Field Success
|
||||
|
||||
Success indicator for validation:
|
||||
|
||||
```django
|
||||
{% include 'forms/partials/field_success.html' with message='Username available' %}
|
||||
|
||||
{# Just checkmark #}
|
||||
{% include 'forms/partials/field_success.html' %}
|
||||
```
|
||||
|
||||
### Form Actions
|
||||
|
||||
Submit and cancel buttons:
|
||||
|
||||
```django
|
||||
{% include 'forms/partials/form_actions.html' %}
|
||||
|
||||
{# With cancel #}
|
||||
{% include 'forms/partials/form_actions.html' with show_cancel=True cancel_url='/list/' %}
|
||||
|
||||
{# With loading state #}
|
||||
{% include 'forms/partials/form_actions.html' with show_loading=True %}
|
||||
|
||||
{# Left-aligned #}
|
||||
{% include 'forms/partials/form_actions.html' with align='left' %}
|
||||
|
||||
{# Custom icon #}
|
||||
{% include 'forms/partials/form_actions.html' with submit_icon='fas fa-check' %}
|
||||
```
|
||||
|
||||
## HTMX Integration
|
||||
|
||||
### Inline Validation
|
||||
|
||||
```django
|
||||
<form hx-post="/submit/" hx-target="#form-results">
|
||||
{% for field in form %}
|
||||
{% include 'forms/partials/form_field.html' with
|
||||
field=field
|
||||
hx_validate=True
|
||||
hx_validate_url='/validate/'
|
||||
%}
|
||||
{% endfor %}
|
||||
{% include 'forms/partials/form_actions.html' with show_loading=True %}
|
||||
</form>
|
||||
```
|
||||
|
||||
### Validation Endpoint Response
|
||||
|
||||
```django
|
||||
{# Success #}
|
||||
{% include 'forms/partials/field_success.html' with message='Valid!' %}
|
||||
|
||||
{# Error #}
|
||||
{% include 'forms/partials/field_error.html' with errors=errors %}
|
||||
```
|
||||
|
||||
## Custom Form Rendering
|
||||
|
||||
For complete control, use the components directly:
|
||||
|
||||
```django
|
||||
<form method="post" action="{% url 'submit' %}">
|
||||
{% csrf_token %}
|
||||
|
||||
{# Non-field errors #}
|
||||
{% if form.non_field_errors %}
|
||||
<div class="mb-4 p-4 bg-red-50 rounded-lg" role="alert">
|
||||
{% for error in form.non_field_errors %}
|
||||
<p>{{ error }}</p>
|
||||
{% endfor %}
|
||||
</div>
|
||||
{% endif %}
|
||||
|
||||
{# Custom field layout #}
|
||||
<div class="grid grid-cols-2 gap-4">
|
||||
{% include 'forms/partials/form_field.html' with field=form.first_name %}
|
||||
{% include 'forms/partials/form_field.html' with field=form.last_name %}
|
||||
</div>
|
||||
|
||||
{% include 'forms/partials/form_field.html' with field=form.email %}
|
||||
|
||||
{% include 'forms/partials/form_actions.html' with submit_text='Create Account' %}
|
||||
</form>
|
||||
```
|
||||
|
||||
## CSS Classes
|
||||
|
||||
The form components use these CSS classes (defined in `components.css`):
|
||||
|
||||
- `.btn-primary` - Primary action button
|
||||
- `.btn-secondary` - Secondary action button
|
||||
- `.form-field` - Field wrapper
|
||||
- `.field-error` - Error message styling
|
||||
|
||||
## Accessibility
|
||||
|
||||
All form components include:
|
||||
|
||||
- Labels properly associated with inputs (`for`/`id`)
|
||||
- Required field indicators with screen reader text
|
||||
- Error messages with `role="alert"`
|
||||
- Help text linked via `aria-describedby`
|
||||
- Invalid state with `aria-invalid`
|
||||
Reference in New Issue
Block a user