Django Template の全体像

Django Template Language (DTL) は Django 標準のテンプレートエンジン。HTML に {% tag %} や {{ variable }} を埋め込み、ビューから渡されたコンテキストで描画します。Jinja2 も切り替え可能ですが、DTL がデフォルトで完備されているので本記事は DTL を扱います。

ステップ 1: settings.py の TEMPLATES 設定

プロジェクト作成時にデフォルトで生成されていますが、DIRS を埋めるのが最初の作業です:

# mysite/settings.py
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],  # ← プロジェクト共通テンプレ
        'APP_DIRS': True,                  # ← 各アプリの templates/ も探索
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

ステップ 2: ディレクトリ構成

mysite/
├── manage.py
├── mysite/
│   ├── settings.py
│   └── urls.py
├── templates/              ← BASE_DIR / 'templates'（共通）
│   ├── base.html
│   └── partials/
│       ├── header.html
│       └── footer.html
└── blog/                   ← アプリ
    ├── views.py
    └── templates/          ← APP_DIRS で自動探索
        └── blog/           ← ★名前衝突回避のためアプリ名でネスト
            ├── index.html
            └── detail.html

重要: アプリの templates ディレクトリは blog/templates/blog/ のようにアプリ名でネストするのが慣例。複数アプリで index.html が衝突するのを防ぎます。

ステップ 3: ビューからテンプレートを呼ぶ

# blog/views.py
from django.shortcuts import render

def index(request):
    context = {
        'posts': Post.objects.all(),
        'site_name': 'My Blog',
    }
    return render(request, 'blog/index.html', context)
    #              ↑ APP_DIRS により blog/templates/blog/index.html を解決

DTL の基本文法

変数表示 {{ ... }}

{{ post.title }}
{{ user.username }}
{{ posts.0.title }}
             {# リストのインデックス #}
{{ post.created_at|date:"Y-m-d" }}
  {# フィルター適用 #}

タグ {% ... %}

{% if user.is_authenticated %}
  
こんにちは {{ user.username }} さん
{% else %}
  ログイン
{% endif %}

{% for post in posts %}
  
{{ post.title }} ({{ forloop.counter }}/{{ posts|length }})
{% empty %}
  
記事はまだありません
{% endfor %}

{% url 'blog:detail' post.pk %}    {# URL 解決 #}
{% csrf_token %}                   {# CSRF トークン #}
{% load humanize %}                {# テンプレタグライブラリ読込 #}

主要フィルター一覧

テンプレート継承 (extends / block)

共通レイアウトを base.html に定義し、各ページで上書きします:

{# templates/base.html #}
{% load static %}



    
    
    


    {% include 'partials/header.html' %}

    

        {% block content %}{% endblock %}
    

    {% include 'partials/footer.html' %}

{# blog/templates/blog/index.html #}
{% extends 'base.html' %}

{% block title %}記事一覧 | {{ block.super }}{% endblock %}

{% block content %}
記事一覧

  {% for post in posts %}
    
{{ post.title }}
  {% endfor %}

{% endblock %}

include で部品化

{# 引数渡し #}
{% include 'partials/card.html' with post=post show_author=True %}

{# 親のコンテキスト引き継がない（独立） #}
{% include 'partials/card.html' with post=post only %}

{% load static %} と静的ファイル

{% load static %}

# settings.py
STATIC_URL = '/static/'
STATICFILES_DIRS = [BASE_DIR / 'static']  # 開発時の追加探索パス
STATIC_ROOT = BASE_DIR / 'staticfiles'    # collectstatic の出力先（本番）

テンプレートのキャッシュ（本番）

# settings.py（本番のみ。DEBUG=True ならコメントアウト）
TEMPLATES = [
    {
        # ...
        'APP_DIRS': False,  # cached.Loader 使用時は False
        'OPTIONS': {
            'loaders': [
                ('django.template.loaders.cached.Loader', [
                    'django.template.loaders.filesystem.Loader',
                    'django.template.loaders.app_directories.Loader',
                ]),
            ],
            'context_processors': [...],
        },
    },
]

FAQ

Q: テンプレートが見つからないと言われる
A: blog/templates/blog/index.html のようにアプリ名でネストしているか確認。また INSTALLED_APPS に登録され APP_DIRS: True である必要があります。

Q: Jinja2 を使いたい
A: TEMPLATES に BACKEND: 'django.template.backends.jinja2.Jinja2' を追加。DTL と並行利用も可。

Q: テンプレートで Python 関数を直接呼びたい
A: 不可（意図的制限）。カスタムテンプレートタグ / フィルターを templatetags/ に作って {% load %} して使います。