thrillwiki_django_no_react/backend/templates/forms/README.md

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:

{% 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:

{% 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:

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

{% 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:

{% 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:

{% include 'forms/partials/field_success.html' with message='Username available' %}

{# Just checkmark #}
{% include 'forms/partials/field_success.html' %}

Form Actions

Submit and cancel buttons:

{% 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

<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

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

<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