85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
---
|
|
name: django-templates
|
|
description: Django template patterns including inheritance, partials, tags, and filters. Use when working with templates, creating reusable components, or organizing template structure.
|
|
---
|
|
|
|
# Django Template Patterns
|
|
|
|
## Template Organization
|
|
|
|
```
|
|
templates/
|
|
├── base.html # Root template with common structure
|
|
├── partials/ # Reusable fragments (navbar, footer, pagination)
|
|
├── components/ # UI components (button, card, modal)
|
|
└── <app>/ # App-specific templates
|
|
├── list.html # Full pages extend base.html
|
|
├── detail.html
|
|
├── _list.html # HTMX partials (underscore prefix)
|
|
└── _form.html
|
|
```
|
|
|
|
**Naming conventions:**
|
|
- Full pages: `list.html`, `detail.html`, `form.html`
|
|
- HTMX partials: `_list.html`, `_card.html` (underscore prefix)
|
|
- Shared partials: `partials/_navbar.html`, `partials/_pagination.html`
|
|
- Components: `components/_button.html`, `components/_modal.html`
|
|
|
|
## Template Inheritance
|
|
|
|
Use three-level inheritance for consistent layouts:
|
|
|
|
1. **base.html** - Site-wide structure (HTML skeleton, navbar, footer)
|
|
2. **Section templates** - Optional intermediate templates for sections with shared elements
|
|
3. **Page templates** - Individual pages that extend base or section templates
|
|
|
|
**Standard blocks to define in base.html:**
|
|
- `title` - Page title (use `{{ block.super }}` to append to site name)
|
|
- `content` - Main page content
|
|
- `extra_css` - Page-specific stylesheets
|
|
- `extra_js` - Page-specific scripts
|
|
|
|
## Partials and Components
|
|
|
|
**Partials** are template fragments included in other templates. Use for:
|
|
- Repeated content (pagination, empty states)
|
|
- HTMX responses that replace portions of the page
|
|
- Keeping templates DRY
|
|
|
|
**Components** are self-contained UI elements with configurable behavior. Pass context with:
|
|
- `{% include "components/_button.html" with text="Submit" variant="primary" %}`
|
|
- Add `only` to isolate context: `{% include "_card.html" with title=post.title only %}`
|
|
|
|
## Custom Tags and Filters
|
|
|
|
**When to create custom template tags:**
|
|
- `simple_tag` - Return a string value (e.g., active link class, formatted output)
|
|
- `inclusion_tag` - Render a template fragment (e.g., pagination component, user avatar)
|
|
|
|
**When to create custom filters:**
|
|
- Transform a single value (e.g., initials from name, percentage calculation)
|
|
- Chain with other filters for composable transformations
|
|
|
|
**Location:** `apps/<app>/templatetags/<app>_tags.py` (create `__init__.py` in templatetags directory)
|
|
|
|
## Anti-Patterns
|
|
|
|
**Move logic out of templates:**
|
|
- Complex conditionals belong in views or model methods
|
|
- Use `user.can_moderate` not `user.role == "admin" or user.role == "moderator"`
|
|
|
|
**Use URL names, not hardcoded paths:**
|
|
- Use `{% url 'posts:detail' pk=post.pk %}` not `/posts/{{ post.id }}/`
|
|
|
|
**Use CSS classes, not inline styles:**
|
|
- Use `class="error-message"` not `style="color: red;"`
|
|
|
|
**Handle empty states:**
|
|
- Always include `{% empty %}` clause in loops that might have no items
|
|
|
|
## Integration with Other Skills
|
|
|
|
- **htmx-patterns** - HTMX partial templates and dynamic UI
|
|
- **django-forms** - Form rendering and validation patterns
|
|
- **pytest-django-patterns** - Testing template rendering
|