Команда Python for Devs подготовила перевод большого туторила по Django Templates. В статье подробно разбирается, как устроен язык шаблонов Django, чем он отличается от Jinja, как правильно наследовать шаблоны и организовать структуру проекта. Если вы хотите сделать свои Django-приложения более чистыми, поддерживаемыми и быстрыми — этот материал для вас.

Django templates — важнейшая часть фреймворка. Понимание того, что это такое и зачем они нужны, поможет вам создавать удобные, гибкие и хорошо работающие шаблоны для ваших сайтов и приложений на Django.

Если вы только начинаете работать с фреймворком и настраиваете свой первый проект на Django, разобраться с шаблонами — критически важно. В этом руководстве вы найдете всё, что нужно знать о Django templates: какие они бывают и как их использовать.

Что такое Django templates?

Django templates — это фундаментальная часть фреймворка Django. Они позволяют отделить визуальное представление сайта от логики кода. Шаблон содержит статические части нужного HTML-вывода и специальный синтаксис, описывающий, как будет подставляться динамическое содержимое.

В конечном итоге шаблоны могут формировать полноценные веб-страницы, тогда как запросы к базе данных и другая обработка данных выполняются во views и моделях. Такое разделение обеспечивает чистый и поддерживаемый код: бизнес-логика HTML отделена от Python-кода в остальной части проекта. Без шаблонов вам пришлось бы вставлять HTML прямо в Python-код, что делало бы его трудночитаемым и сложным для отладки.

Пример Django шаблона с HTML, переменной name и простой логикой if/else:

<h1>Welcome!</h1>
{% if name %}
  <h1>Hello, {{ name }}!</h1>
{% else %}
  <h1>Hello, Guest!</h1>
{% endif %}
<h1>{{ heading }}</h1>

Преимущества использования шаблонов

Разработчики используют Django templates, чтобы быстро и эффективно создавать надежные приложения. Среди ключевых преимуществ шаблонов:

Повторное использование кода: можно создавать переиспользуемые компоненты и макеты для единообразия страниц и приложений.
Удобная поддержка: внешний вид веб-страниц можно менять без изменения логики.
Лучшая читаемость: HTML остаётся чистым и понятным, без лишней сложной логики.
Наследование шаблонов: можно определить общие структуры и макеты, чтобы сократить дублирование и обеспечить единый стиль.
Динамическое содержимое: есть возможность строить персонализированные страницы, которые подстраиваются под ввод пользователя и изменения данных.
Оптимизация производительности: шаблоны можно кэшировать, ускоряя работу приложения или сайта.

Сложности и ограничения

Хотя шаблоны — ключевой инструмент для отображения веб-страниц в Django, использовать их нужно с умом, особенно в сложных проектах с большими наборами данных. Несмотря на простоту языка шаблонов Django, слишком сложные шаблоны с множеством вложенных тегов, фильтров и наследований становятся трудными в поддержке. Вместо того чтобы вкладывать в шаблоны слишком много логики, лучше сосредоточить их на отображении данных. Возможности кастомизации тоже ограничены, если вы не создаёте собственные теги или фильтры.

Переход на другой движок шаблонов может быть непростой задачей, так как стандартный движок Django тесно интегрирован с фреймворком. Однако переход на альтернативы вроде Jinja относительно прост, и мы обсудим этот вариант позже в руководстве.

Отладка Django шаблонов

В некоторых случаях (например, при возникновении ошибок) полезно посмотреть, как работает ваш шаблон. Для этого существует отладка шаблонов.

Отладка шаблонов помогает выявить ошибки во взаимодействии HTML и динамических данных. Частые проблемы: отсутствующие переменные, неправильные теги и ошибки в логике.

К счастью, Django предлагает полезные инструменты — например, {{ debug }} для просмотра содержимого шаблонов и подробные страницы ошибок, которые указывают на место проблемы. Это упрощает поиск и устранение ошибок, позволяя убедиться, что шаблоны отображаются так, как задумано.

Понимание языка шаблонов Django (DTL)

Django Template Language (DTL) — встроенный в Django движок шаблонов, созданный для упрощения разработки динамических веб-страниц. Он органично сочетает HTML с тегами и фильтрами Django, позволяя генерировать богатое, основанное на данных содержимое прямо из вашего приложения. Давайте разберём ключевые особенности, которые делают DTL мощным инструментом для создания шаблонов.

Базовый синтаксис и структура DTL

Шаблоны Django пишутся с использованием комбинации HTML и синтаксиса DTL. Основная структура шаблона состоит из HTML-разметки с внедрёнными тегами и переменными Django.

Пример:

<!DOCTYPE html>
<html>
  <head>
    <title>{{ page_title }}</title>
  </head>
  <body>
    <h1>{{ heading }}</h1>
    <ul>
      {% for item in item_list %}
        <li>{{ item.name }}</li>
      {% endfor %}
    </ul>
  </body>
</html>

Переменные, фильтры и теги

DTL предоставляет несколько возможностей для работы с переменными, фильтрами и тегами:

Переменные: отображают динамические данные в шаблонах. Они заключаются в двойные фигурные скобки, например {{ variable_name }}.
Фильтры: изменяют или форматируют значение переменной перед её отображением. Применяются с помощью вертикальной черты ( | ), например {{ variable_name|upper }}.
Теги: управляют логикой и потоком выполнения шаблона. Заключаются в блоки {% %} и позволяют выполнять циклы, условия и включения других шаблонов.

Наследование шаблонов и расширение базовых шаблонов

Система наследования шаблонов в Django позволяет создавать базовый шаблон, который содержит стандартную структуру и макет для вашего сайта или приложения.

Затем вы можете создавать дочерние шаблоны, которые наследуют этот базовый шаблон и при необходимости переопределяют отдельные блоки. Это способствует повторному использованию кода и единообразию всех страниц.

Чтобы создать базовый шаблон, определите блоки с помощью тега {% block %}:

<!-- base.html -->
<!DOCTYPE html>
<html>
  <head>
    <title>{% block title %}Default Title{% endblock %}</title>
  </head>
  <body>
    {% block content %}
    {% endblock %}
  </body>
</html>

Дочерние шаблоны расширяют базовые и переопределяют нужные блоки:

<!-- child_template.html -->
{% extends 'base.html' %}
{% block title %}My Page Title{% endblock %}
{% block content %}
  <h1>My Page Content</h1>
  <p>This is the content of my page.</p>
{% endblock %}

Теги Django в шаблонах

Теги — важнейший элемент Django templates. Они предоставляют широкий набор возможностей: от условного рендеринга и циклов до наследования и включения других шаблонов.

Давайте рассмотрим их подробнее.

Основные теги Django шаблонов

В Django есть множество тегов, но вот те, которые вы будете использовать чаще всего:

{% if %}: позволяет условно отображать содержимое на основе заданного условия. Часто используется вместе с тегами {% else %} и {% elif %}.
{% for %}: используется для перебора последовательности, например списка или queryset, и рендеринга содержимого для каждого элемента.
{% include %}: подключает содержимое другого шаблона в текущий. Удобно для повторного использования общих фрагментов кода на разных страницах.
{% block %}: применяется совместно с наследованием шаблонов. Определяет блок содержимого, который может быть переопределён дочерним шаблоном.
{% extends %}: указывает базовый шаблон, от которого наследуется текущий.
{% url %}: генерирует URL для именованного маршрута в вашем проекте Django. Помогает отвязать шаблон от конкретных путей.
{% load %}: загружает кастомные теги и фильтры из Python-модуля или библиотеки, расширяя возможности системы шаблонов Django.

Это лишь часть доступных тегов. Теги вроде {% with %}, {% cycle %}, {% comment %} и другие дают ещё больше возможностей для сложных проектов, помогая создавать более гибкие и эффективные приложения.

Использование тегов в шаблонах

Пример использования тегов в Django шаблоне:

{% extends 'base.html' %}
{% load custom_filters %}
{% block content %}
  <h1>{{ page_title }}</h1>
  {% if object_list %}
    <ul>
      {% for obj in object_list %}
        <!-- Обрезаем имя объекта до 25 символов -->
        <li>{{ obj.name|truncate:25 }}</li>
      {% endfor %}
    </ul>
  {% else %}
    <p>No objects found.</p>
  {% endif %}
  {% include 'partials/pagination.html' %}
{% endblock %}

В этом примере мы расширяем базовый шаблон, подключаем кастомные фильтры и определяем блок для основного содержимого.

Внутри блока мы проверяем наличие object_list. Если список есть, перебираем его и отображаем обрезанные имена объектов. Если списка нет, выводим сообщение «No objects found».

В конце мы подключаем частичный шаблон с пагинацией. Такой шаблон — это переиспользуемый HTML-фрагмент, который можно включать в другие шаблоны, чтобы централизованно управлять общими элементами, например пагинацией.

Шаблоны админки

Встроенная админка Django предоставляет удобный и интуитивный способ управления данными приложения. Она работает на основе набора шаблонов, определяющих его структуру, макет и внешний вид.

Возможности

Шаблоны админки отвечают за множество задач:

Аутентификация: управление аутентификацией пользователей, входом и выходом из системы.
Управление моделями: отображение списков экземпляров моделей, а также создание, редактирование и удаление этих экземпляров.
Отрисовка форм: формирование форм для создания и редактирования записей.
Навигация: отображение структуры навигации, включая главное меню и подменю для отдельных приложений.
Пагинация: отображение элементов управления пагинацией при работе со списками объектов.
История изменений: показ и управление историей изменений записей.

Встроенные шаблоны админки дают прочную основу для управления данными вашего приложения.

Кастомизация шаблонов админки

Хотя админка Django из коробки предлагает удобный и функциональный интерфейс, иногда может понадобиться адаптировать его под нужды конкретного проекта.

Вы можете изменить внешний вид, улучшить UX или добавить уникальные возможности для своего приложения.

Вот несколько способов сделать это:

Переопределение шаблонов: создайте шаблоны с той же структурой и именами в директории templatesвашего проекта. Django автоматически подставит ваши версии вместо стандартных.
Расширение базовых шаблонов: многие шаблоны админки построены с использованием механизма наследования. Вы можете создать шаблон, который расширяет базовый, и переопределить только нужные блоки.
Настройка параметров шаблонов: Django позволяет настраивать поведение интерфейса — например, какие поля отображать, какие из них редактируемые, или использовать кастомные шаблоны для отдельных полей модели.
Кастомизация сайта админки: внешний вид и поведение можно изменить, создав собственный класс, наследующий AdminSite, и зарегистрировав его в проекте.

URL-шаблоны в Django

URL-шаблоны в Django предлагают гибкий способ определения и генерации адресов для веб-приложений.

Понимание URL-шаблонов

В Django маршруты определяются в файле urls.py с помощью функции path из модуля django.urls.

Эти маршруты сопоставляют определённые URL-паттерны с Python-функциями (views), которые обрабатывают соответствующие HTTP-запросы.

Пример базового маршрута в Django:

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
    path('about/', views.about, name='about'),
]

В этом примере маршрут '' (корень сайта) связан с функцией views.home, а маршрут 'about/' — с функцией views.about.

Динамическая генерация URL с помощью шаблонов

URL-шаблоны в Django позволяют добавлять переменные или параметры в маршруты. Это даёт возможность создавать динамические URL, которые могут представлять разные экземпляры одного ресурса или содержать дополнительные данные.

Если ваш urls.py подключает другие файлы маршрутов с помощью include(), PyCharm автоматически собирает и распознаёт все вложенные маршруты. Благодаря этому автодополнение имён URL остаётся точным, а вы можете перейти к определению маршрута по Ctrl+Click на его имени — даже если маршрут описан во вложенном файле.

Пример URL-шаблона с переменной:

# urls.py
urlpatterns = [
    path('blog/<int:year>/', views.year_archive, name='blog_year_archive'),
]

В этом случае маршрут 'blog/<int:year>/' содержит переменную year типа int. Когда запрос соответствует этому паттерну, Django передаёт значение year в качестве аргумента функции views.year_archive.

Использование Django URL

Django URL — это основа любого приложения. Они связывают запросы пользователя с соответствующими view-функциями. Определяя URL-паттерны, которые сопоставляются с конкретными views, вы сохраняете сайт организованным и масштабируемым.

Использование URL-шаблонов с функцией reverse

Функция reverse в Django позволяет генерировать URL на основе их именованных паттернов. Она принимает имя маршрута в качестве первого аргумента, затем необходимые параметры, и возвращает соответствующий URL.

Пример:

# views.py
from django.shortcuts import render
from django.urls import reverse

def blog_post_detail(request, year, month, slug):
    # ...
    url = reverse('blog_post_detail', args=[year, month, slug])
    return render(request, 'blog/post_detail.html', {'url': url})

Здесь функция reverse используется для генерации URL по имени маршрута blog_post_detail, передавая значения year, month и slug в качестве аргументов.

Полученный URL можно использовать в шаблонах или в других частях приложения.

Использование URL-тегов в шаблонах Django

Тег шаблона {% url %} — удобный способ генерировать URL прямо в шаблоне. Вместо того чтобы хардкодить адреса, вы ссылаетесь на именованные маршруты, что делает шаблоны более гибкими и простыми в поддержке.

Пример:

<a href="{% url 'blog_post_detail' year=2024 month=10 slug=post.slug %}"> 
  Read More 
</a>

В этом случае тег {% url %} формирует адрес для view blog_post_detail, передавая параметры year, month и slug. Важно, чтобы аргументы соответствовали маршруту, описанному в urls.py, который должен выглядеть так:

path('blog/<int:year>/<int:month>/<slug:slug>/', views.blog_post_detail, name='blog_post_detail'),

Такой подход помогает держать шаблоны чистыми и гибкими, особенно по мере развития проекта.

Jinja vs. Django templates

Хотя Django поставляется со встроенным движком шаблонов (DTL), разработчики могут использовать и альтернативы, например Jinja.

Jinja — это популярный, современный и богатый возможностями движок шаблонов для Python. Изначально он был разработан для фреймворка Flask, но также совместим и с Django.

Движок создавался с упором на скорость, безопасность и расширяемость. Благодаря широкому набору функций он отлично подходит для рендеринга динамического содержимого.

Ключевые особенности и преимущества Jinja по сравнению с DTL:

Более лаконичный и интуитивный синтаксис.
Изолированное выполнение (sandboxed execution), повышающее безопасность и защищающее от атак с внедрением кода.
Более гибкая и мощная система наследования шаблонов.
Улучшенные инструменты отладки и механизмы отчетности.
Более высокая производительность при работе со сложными шаблонами и большими объёмами данных.
Расширенный функционал благодаря встроенным фильтрам и макросам, позволяющим писать более сложную логику без перегрузки шаблона.

PyCharm автоматически определяет файлы с расширением *.jinja, обеспечивает подсветку синтаксиса, автодополнение, обнаружение ошибок и поддержку кастомных фильтров и расширений, что делает процесс разработки удобным.

Тем не менее стоит учитывать, что интеграция Jinja в проект Django требует более сложной настройки и дополнительной конфигурации.

Некоторые разработчики предпочитают оставаться на встроенном движке Django, чтобы не выходить за рамки экосистемы фреймворка.

Русскоязычное сообщество про Python

Друзья! Эту статью перевела команда Python for Devs — канала, где каждый день выходят самые свежие и полезные материалы о Python и его экосистеме. Подписывайтесь, чтобы ничего не пропустить!

Использование Django шаблонов: лучшие практики и советы

Работа с Django templates — отличный способ управлять уровнем представления ваших веб-приложений.

Однако важно следовать рекомендациям и оптимизировать производительность, чтобы шаблоны оставались удобными в поддержке, безопасными и системными.

Вот несколько советов и лучших практик при работе с Django шаблонами:

Разделяйте представление и бизнес-логику. Шаблоны должны заниматься исключительно отображением данных, а сложная обработка должна выполняться во views или моделях.
Логично организуйте шаблоны. Следуйте файловой структуре Django, разделяйте шаблоны по приложениям и функциям, при необходимости используйте подкаталоги.
Используйте соглашения об именах Django. Django следует принципу «соглашение важнее конфигурации», поэтому можно называть шаблоны определённым образом, чтобы не указывать их явно. Например, при использовании class-based views, таких как ListView, Django автоматически ищет шаблон с именем <app_name>/<model_name>_list.html, что упрощает код.
Делите большие задачи на переиспользуемые компоненты. Используйте теги, фильтры и include, чтобы сокращать дублирование и улучшать поддерживаемость кода.
Придерживайтесь единых соглашений об именах. Даёте ли вы имена шаблонам, тегам или фильтрам — они должны быть понятными и описательными, чтобы другим разработчикам было легко читать ваш код.
Используйте фильтры безопасного рендеринга Django. Всегда экранируйте данные, полученные от пользователя, чтобы защититься от XSS-уязвимостей.
Документируйте сложную логику. Пишите понятные комментарии к сложным участкам шаблонов — это поможет коллегам (и вам самим в будущем) быстрее понять код.
Профилируйте шаблоны. Используйте инструменты профилирования Django для поиска и оптимизации узких мест, таких как неэффективные циклы или избыточная логика.

Django Templates: всё, что вам нужно знать