mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2026-02-06 12:54:41 -05:00
Add standardized HTMX conventions, interaction patterns, and migration guide for ThrillWiki UX
This commit is contained in:
pacnpal
191
backend/templates/htmx/components/README.md
Normal file
191
backend/templates/htmx/components/README.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# HTMX Components
|
||||
|
||||
This directory contains HTMX-related template components for loading states, error handling, and success feedback.
|
||||
|
||||
## Loading State Guidelines
|
||||
|
||||
### When to Use Each Type
|
||||
|
||||
| Scenario | Component | Example |
|
||||
|----------|-----------|---------|
|
||||
| Initial page load, full content replacement | Skeleton screens | Parks list loading |
|
||||
| Button actions, form submissions | Loading indicator (inline) | Submit button spinner |
|
||||
| Partial content updates | Loading indicator (block) | Search results loading |
|
||||
| Container replacement | Loading indicator (overlay) | Modal content loading |
|
||||
|
||||
### Components
|
||||
|
||||
#### loading_indicator.html
|
||||
|
||||
Standardized loading indicator for HTMX requests with three modes:
|
||||
|
||||
**Inline Mode** - For buttons and links:
|
||||
```django
|
||||
<button hx-post="/api/action" hx-indicator="#btn-loading">
|
||||
Save
|
||||
{% include 'htmx/components/loading_indicator.html' with id='btn-loading' mode='inline' %}
|
||||
</button>
|
||||
```
|
||||
|
||||
**Block Mode** (default) - For content areas:
|
||||
```django
|
||||
<div hx-get="/api/list" hx-indicator="#list-loading">
|
||||
<!-- Content -->
|
||||
</div>
|
||||
{% include 'htmx/components/loading_indicator.html' with id='list-loading' %}
|
||||
```
|
||||
|
||||
**Overlay Mode** - For containers:
|
||||
```django
|
||||
<div class="relative" hx-get="/api/data" hx-indicator="#overlay-loading">
|
||||
<!-- Content to cover -->
|
||||
{% include 'htmx/components/loading_indicator.html' with id='overlay-loading' mode='overlay' %}
|
||||
</div>
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `id` | str | - | ID for hx-indicator targeting |
|
||||
| `message` | str | "Loading..." | Loading text to display |
|
||||
| `mode` | str | "block" | 'inline', 'block', or 'overlay' |
|
||||
| `size` | str | "md" | 'sm', 'md', or 'lg' |
|
||||
| `spinner` | str | "border" | 'spin' (fa-spinner) or 'border' (CSS) |
|
||||
|
||||
## Skeleton Screens
|
||||
|
||||
Located in `components/skeletons/`, these provide content-aware loading placeholders:
|
||||
|
||||
### Available Skeletons
|
||||
|
||||
| Component | Use Case |
|
||||
|-----------|----------|
|
||||
| `list_skeleton.html` | List views, search results |
|
||||
| `card_grid_skeleton.html` | Card-based grid layouts |
|
||||
| `detail_skeleton.html` | Detail/show pages |
|
||||
| `form_skeleton.html` | Form loading states |
|
||||
| `table_skeleton.html` | Data tables |
|
||||
|
||||
### Usage with HTMX
|
||||
|
||||
```django
|
||||
{# Initial content shows skeleton, replaced by HTMX #}
|
||||
<div id="parks-list"
|
||||
hx-get="/parks/"
|
||||
hx-trigger="load"
|
||||
hx-swap="innerHTML">
|
||||
{% include 'components/skeletons/card_grid_skeleton.html' with cards=6 %}
|
||||
</div>
|
||||
```
|
||||
|
||||
### With hx-indicator
|
||||
|
||||
```django
|
||||
<div id="results">
|
||||
<!-- Results here -->
|
||||
</div>
|
||||
|
||||
{# Skeleton shown during loading #}
|
||||
<div id="results-skeleton" class="htmx-indicator">
|
||||
{% include 'components/skeletons/list_skeleton.html' %}
|
||||
</div>
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### error_message.html
|
||||
|
||||
Displays error messages with consistent styling:
|
||||
|
||||
```django
|
||||
{% include 'htmx/components/error_message.html' with
|
||||
message="Unable to load data"
|
||||
show_retry=True
|
||||
retry_url="/api/data"
|
||||
%}
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `message` | str | - | Error message text |
|
||||
| `code` | str | - | HTTP status code |
|
||||
| `show_retry` | bool | False | Show retry button |
|
||||
| `retry_url` | str | - | URL for retry action |
|
||||
| `show_report` | bool | False | Show "Report Issue" link |
|
||||
|
||||
## Success Feedback
|
||||
|
||||
### success_toast.html
|
||||
|
||||
Triggers a toast notification via HTMX response:
|
||||
|
||||
```django
|
||||
{% include 'htmx/components/success_toast.html' with
|
||||
message="Park saved successfully"
|
||||
type="success"
|
||||
%}
|
||||
```
|
||||
|
||||
### Using HX-Trigger Header
|
||||
|
||||
From views, trigger toasts via response headers:
|
||||
|
||||
```python
|
||||
from django.http import HttpResponse
|
||||
|
||||
def save_park(request):
|
||||
# ... save logic ...
|
||||
response = HttpResponse()
|
||||
response['HX-Trigger'] = json.dumps({
|
||||
'showToast': {
|
||||
'type': 'success',
|
||||
'message': 'Park saved successfully'
|
||||
}
|
||||
})
|
||||
return response
|
||||
```
|
||||
|
||||
## HTMX Configuration
|
||||
|
||||
The base template configures HTMX with:
|
||||
|
||||
- 30-second timeout
|
||||
- Global view transitions enabled
|
||||
- Template fragments enabled
|
||||
- Comprehensive error handling
|
||||
|
||||
### Swap Strategies
|
||||
|
||||
| Strategy | Use Case |
|
||||
|----------|----------|
|
||||
| `innerHTML` | Replace content inside container (lists, search results) |
|
||||
| `outerHTML` | Replace entire element (status badges, individual items) |
|
||||
| `beforeend` | Append items (infinite scroll) |
|
||||
| `afterbegin` | Prepend items (new items at top) |
|
||||
|
||||
### Target Naming Conventions
|
||||
|
||||
- `#object-type-id` - For specific objects (e.g., `#park-123`)
|
||||
- `#section-name` - For page sections (e.g., `#results`, `#filters`)
|
||||
- `#modal-container` - For modals
|
||||
- `this` - For self-replacement
|
||||
|
||||
### Custom Events
|
||||
|
||||
- `{model}-status-changed` - Status updates (e.g., `park-status-changed`)
|
||||
- `auth-changed` - Authentication state changes
|
||||
- `{model}-created` - New item created
|
||||
- `{model}-updated` - Item updated
|
||||
- `{model}-deleted` - Item deleted
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always specify hx-indicator** for user feedback
|
||||
2. **Use skeleton screens** for initial page loads and full content replacement
|
||||
3. **Use inline indicators** for button actions
|
||||
4. **Use overlay indicators** for modal content loading
|
||||
5. **Add aria attributes** for accessibility (role="status", aria-busy)
|
||||
6. **Clean up loading states** after request completion (automatic with HTMX)
|
||||
Reference in New Issue
Block a user