django-templates

Django テンプレートのパターン

テンプレートの構成

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

命名規則：

• ページ全体：list.html、detail.html、form.html
• HTMX の部分テンプレート：_list.html、_card.html（先頭にアンダースコア）
• 共有する部分テンプレート：partials/_navbar.html、partials/_pagination.html
• コンポーネント：components/_button.html、components/_modal.html

テンプレートの継承

一貫したレイアウトにするため、3 段階の継承を使用します。

1. base.html - サイト全体の構造（HTML の骨組み、ナビゲーションバー、フッター）
2. セクションテンプレート - 共通要素があるセクション向けの、中間テンプレート（任意）
3. ページテンプレート - base テンプレートまたはセクションテンプレートを継承する個々のページ

base.html で定義する標準ブロック：

• title - ページタイトル（サイト名を末尾に追加するには {{ block.super }} を使用）
• content - ページのメインコンテンツ
• extra_css - ページ固有のスタイルシート
• extra_js - ページ固有のスクリプト

部分テンプレートとコンポーネント

部分テンプレートは、他のテンプレートに読み込まれるテンプレートの断片です。次の用途に使用します。

• 繰り返し表示するコンテンツ（ページネーション、空の状態）
• ページの一部を置き換える HTMX のレスポンス
• テンプレートを DRY に保つ

コンポーネントは、動作を設定できる独立した UI 要素です。次のようにコンテキストを渡します。

• {% include "components/_button.html" with text="Submit" variant="primary" %}
• only を追加してコンテキストを分離します：{% include "_card.html" with title=post.title only %}

カスタムタグとフィルター

カスタムテンプレートタグを作成する場合：

• simple_tag - 文字列値を返します（例：アクティブなリンクのクラス、フォーマット済みの出力）
• inclusion_tag - テンプレートの断片をレンダリングします（例：ページネーションコンポーネント、ユーザーアバター）

カスタムフィルターを作成する場合：

• 単一の値を変換します（例：名前からイニシャルを取得、割合を計算）
• 他のフィルターと組み合わせて、再利用可能な変換を行います

配置場所： apps/<app>/templatetags/<app>_tags.py（templatetags ディレクトリに __init__.py を作成します）

アンチパターン

テンプレートからロジックを取り除きます。

• 複雑な条件分岐はビューまたはモデルメソッドに記述します
• user.role == "admin" or user.role == "moderator" ではなく、user.can_moderate を使用します

ハードコードしたパスではなく、URL 名を使用します。

• /posts/{{ post.id }}/ ではなく、{% url 'posts:detail' pk=post.pk %} を使用します

インラインスタイルではなく、CSS クラスを使用します。

• style="color: red;" ではなく、class="error-message" を使用します

空の状態を処理します。

• 項目がない場合があるループには、必ず {% empty %} 節を含めます

他のスキルとの連携

• htmx-patterns - HTMX の部分テンプレートと動的 UI
• django-forms - フォームのレンダリングとバリデーションのパターン
• pytest-django-patterns - テンプレートのレンダリングテスト