Django Templates

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