# Template Structure and Conventions - Public Web Frontend **Last Updated:** November 18, 2025 --- ## Overview This document outlines the template structure, naming conventions, and best practices for Jinja2 templates in the Code of Conquest web frontend. **Template Philosophy:** - Clean, semantic HTML - Separation of concerns (templates, styles, scripts) - Reusable components via includes and macros - Responsive design patterns - Accessibility-first --- ## Directory Structure ``` templates/ ├── base.html # Base template (all pages extend this) ├── errors/ # Error pages │ ├── 404.html │ ├── 500.html │ └── 403.html ├── auth/ # Authentication pages │ ├── login.html │ ├── register.html │ └── forgot_password.html ├── dashboard/ # User dashboard │ └── index.html ├── characters/ # Character management │ ├── list.html │ ├── create.html │ ├── view.html │ └── edit.html ├── sessions/ # Game sessions │ ├── create.html │ ├── active.html │ ├── history.html │ └── view.html ├── multiplayer/ # Multiplayer sessions │ ├── create.html │ ├── lobby.html │ ├── session.html │ └── complete.html ├── partials/ # Reusable partial templates │ ├── navigation.html │ ├── footer.html │ ├── character_card.html │ ├── combat_ui.html │ └── session_summary.html ├── components/ # Reusable UI components (macros) │ ├── forms.html │ ├── buttons.html │ ├── alerts.html │ └── modals.html └── macros/ # Jinja2 macros ├── form_fields.html └── ui_elements.html ``` --- ## Base Template **File:** `templates/base.html` ```html {% block title %}Code of Conquest{% endblock %} {% block extra_css %}{% endblock %} {% block extra_head %}{% endblock %} {% include 'partials/navigation.html' %}
{% block flash_messages %} {% with messages = get_flashed_messages(with_categories=true) %} {% if messages %}
{% for category, message in messages %}
{{ message }}
{% endfor %}
{% endif %} {% endwith %} {% endblock %} {% block content %} {% endblock %}
{% include 'partials/footer.html' %} {% block extra_js %}{% endblock %} ``` --- ## Template Naming Conventions ### File Names - Use lowercase with underscores: `character_list.html`, `session_create.html` - Partial templates prefix with underscore: `_card.html`, `_form.html` (optional) - Component files describe what they contain: `forms.html`, `buttons.html` ### Template Variables - Use snake_case: `character`, `session_data`, `user_info` - Prefix collections with descriptive names: `characters_list`, `sessions_active` - Boolean flags use `is_` or `has_` prefix: `is_authenticated`, `has_premium` ### Block Names - Use descriptive names: `{% block sidebar %}`, `{% block page_header %}` - Common blocks: - `title` - Page title - `content` - Main content area - `extra_css` - Additional CSS files - `extra_js` - Additional JavaScript files - `extra_head` - Additional head elements --- ## Template Patterns ### Extending Base Template ```html {% extends "base.html" %} {% block title %}Character List - Code of Conquest{% endblock %} {% block content %}

Your Characters

{% endblock %} {% block extra_js %} {% endblock %} ``` ### Including Partial Templates ```html {% include 'partials/character_card.html' with character=char %} ``` **Or without context:** ```html {% include 'partials/navigation.html' %} ``` ### Using Macros **Define macro** in `templates/macros/form_fields.html`: ```html {% macro text_input(name, label, value="", required=False, placeholder="") %}
{% endmacro %} ``` **Use macro:** ```html {% from 'macros/form_fields.html' import text_input %}
{{ text_input('character_name', 'Character Name', required=True, placeholder='Enter name') }}
``` ### Conditional Rendering ```html {% if user.is_authenticated %}

Welcome, {{ user.username }}!

{% else %} Login {% endif %} ``` ### Loops ```html
{% for character in characters %}

{{ character.name }}

Level {{ character.level }} {{ character.player_class.name }}

{% else %}

No characters found. Create one?

{% endfor %}
``` --- ## HTMX Integration in Templates ### Basic HTMX Attributes ```html
``` ### HTMX with Confirmation ```html ``` ### HTMX Polling ```html
Loading...
``` --- ## Component Patterns ### Character Card Component **File:** `templates/partials/character_card.html` ```html

{{ character.name }}

Lvl {{ character.level }}

{{ character.player_class.name }}

HP: {{ character.current_hp }}/{{ character.max_hp }} | Gold: {{ character.gold }}

View Play
``` **Usage:** ```html {% for character in characters %} {% include 'partials/character_card.html' with character=character %} {% endfor %} ``` ### Alert Component Macro **File:** `templates/components/alerts.html` ```html {% macro alert(message, category='info', dismissible=True) %} {% endmacro %} ``` **Usage:** ```html {% from 'components/alerts.html' import alert %} {{ alert('Character created successfully!', 'success') }} {{ alert('Invalid character name', 'error') }} ``` --- ## Accessibility Guidelines ### Semantic HTML - Use proper heading hierarchy (`

`, `

`, etc.) - Use `