API рендеринга форм

Виджеты форм Django рендерятся с помощью системы шаблонов Django template engines system.

Процесс рендеринга форм можно настроить на нескольких уровнях:

• Виджеты могут указывать пользовательские имена шаблонов.
• Формы и виджеты могут указывать пользовательские классы рендереров.
• Шаблон виджета может быть переопределён проектом. (Приложения с возможностью повторного использования обычно не должны переопределять встроенные шаблоны, так как они могут конфликтовать с пользовательскими шаблонами проекта.)

API низкоуровневого рендеринга

Рендеринг шаблонов форм контролируется настраиваемым классом рендерера. Пользовательский рендерер можно указать, обновив настройку FORM_RENDERER. По умолчанию это 'django.forms.renderers.DjangoTemplates'.

Указав пользовательский рендерер форм и переопределив form_template_name, вы можете настроить стандартный вид разметки форм во всём проекте из одного места.

Вы также можете предоставить пользовательский рендерер для каждой формы или каждого виджета, установив атрибут Form.default_renderer или используя аргумент renderer метода Form.render() или Widget.render().

Аналогичные принципы применимы к рендерингу наборов форм. Подробнее см. Использование набора форм в представлениях и шаблонах.

Используйте один из встроенных рендереров шаблонов форм или реализуйте свой собственный. Пользовательские рендеры должны реализовывать метод render(template_name, context, request=None). Он должен возвращать отрендеренный шаблон (в виде строки) или вызывать исключение TemplateDoesNotExist.

class BaseRenderer

Базовый класс для встроенных рендереров форм.

form_template_name

Добавлен в Django 4.1.

Имя шаблона по умолчанию для рендеринга формы.

По умолчанию "django/forms/default.html", что является псевдонимом для "django/forms/table.html".

Устарело начиная с версии 4.1.

Шаблон "django/forms/default.html" устарел и будет удалён в Django 5.0. По умолчанию будет "django/forms/div.html".

formset_template_name

Добавлен в Django 4.1.

Имя шаблона по умолчанию для рендеринга набора форм.

По умолчанию "django/forms/formsets/default.html", что является псевдонимом для "django/forms/formsets/table.html".

Устарело начиная с версии 4.1.

Шаблон "django/forms/formset/default.html" устарел и будет удалён в Django 5.0. По умолчанию будет шаблон "django/forms/formset/div.html".

get_template(template_name)

Подклассы должны реализовать этот метод с соответствующей логикой поиска шаблонов.

render(template_name, context, request=None)

Рендерит заданный шаблон или вызывает исключение TemplateDoesNotExist.

Встроенные рендеры шаблонов форм

DjangoTemplates

class DjangoTemplates

Этот рендерер использует автономный движок DjangoTemplates (не связанный с тем, что вы можете настроить в настройке TEMPLATES). Он загружает шаблоны сначала из каталога встроенных шаблонов форм в django/forms/templates, а затем из каталогов шаблонов установленных приложений, используя загрузчик app_directories.

Если вы хотите рендерить шаблоны с настройками из вашей настройки TEMPLATES, например, с обработчиками контекста, используйте рендерер TemplatesSetting.

class DjangoDivFormRenderer

Подкласс DjangoTemplates, который указывает form_template_name и formset_template_name как "django/forms/div.html" и "django/forms/formset/div.html" соответственно.

Это переходный рендерер для включения новых шаблонов на основе <div>, которые являются стандартными начиная с Django 5.0.

Применяется через настройку FORM_RENDERER:

FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"

После того, как шаблоны <div> станут стандартными, этот переходный рендерер устареет и будет удалён в Django 6.0. Объявление FORM_RENDERER можно удалить в это время.

Jinja2

class Jinja2

Этот рендерер такой же, как рендерер DjangoTemplates, за исключением того, что он использует бэкенд Jinja2. Шаблоны для встроенных виджетов находятся в django/forms/jinja2, а установленные приложения могут предоставлять шаблоны в каталоге jinja2.

Для использования этого бэкенда все формы и виджеты в вашем проекте и сторонних приложениях должны иметь шаблоны Jinja2. Если вы не предоставите собственные шаблоны Jinja2 для виджетов, у которых их нет, вы не сможете использовать этот рендерер. Например, django.contrib.admin не содержит шаблонов Jinja2 для своих виджетов из-за использования Django тегов.

class Jinja2DivFormRenderer

Переходный рендерер, как и DjangoDivFormRenderer, но наследующийся от Jinja2 для использования с бэкендом Jinja2.

Применяется через настройку FORM_RENDERER:

FORM_RENDERER = "django.forms.renderers.Jinja2DivFormRenderer"

TemplatesSetting

class TemplatesSetting

Этот рендерер даёт вам полный контроль над источниками шаблонов форм и виджетов. Он использует get_template() для поиска шаблонов на основе настроек в TEMPLATES настройке.

Использование этого рендерера вместе со встроенными шаблонами требует либо:

• 'django.forms' в INSTALLED_APPS и по крайней мере одного движка с APP_DIRS=True.

• Добавления каталога встроенных шаблонов в DIRS одного из ваших движков шаблонов. Для генерации пути:

  import django
  
  django.__path__[0] + "/forms/templates"  # or '/forms/jinja2'
  

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

Контекст, доступный в шаблонах наборов форм

Шаблоны наборов форм получают контекст от BaseFormSet.get_context(). По умолчанию наборы форм получают словарь со следующими значениями:

• formset: Экземпляр набора форм.

Контекст, доступный в шаблонах форм

Шаблоны форм получают контекст от Form.get_context(). По умолчанию формы получают словарь со следующими значениями:

• form: Связанная форма.
• fields: Все связанные поля, кроме скрытых.
• hidden_fields: Все скрытые связанные поля.
• errors: Все ошибки формы, не связанные с полями или скрытыми полями.

Контекст, доступный в шаблонах виджетов

Шаблоны виджетов получают контекст из Widget.get_context(). По умолчанию виджеты получают в контексте единственное значение, widget. Это словарь, содержащий значения, такие как:

• name
• value
• attrs
• is_hidden
• template_name

Некоторые виджеты добавляют дополнительную информацию в контекст. Например, все виджеты, которые являются подклассами Input, определяют widget['type'], а MultiWidget определяет widget['subwidgets'] для целей циклов.

Переопределение встроенных шаблонов formset

BaseFormSet.template_name

Для переопределения шаблонов formset необходимо использовать рендерер TemplatesSetting. Тогда переопределение шаблонов formset работает так же, как переопределение любого другого шаблона в вашем проекте.

Переопределение встроенных шаблонов форм

Form.template_name

Для переопределения шаблонов форм необходимо использовать рендерер TemplatesSetting. Тогда переопределение шаблонов форм работает так же, как переопределение любого другого шаблона в вашем проекте.

Переопределение встроенных шаблонов виджетов

Каждый виджет имеет атрибут template_name со значением, например, input.html. Встроенные шаблоны виджетов хранятся в пути django/forms/widgets. Вы можете предоставить пользовательский шаблон для input.html, определив django/forms/widgets/input.html, например. См. Встроенные виджеты для имени шаблона каждого виджета.

Для переопределения шаблонов виджетов необходимо использовать рендерер TemplatesSetting. Тогда переопределение шаблонов виджетов работает так же, как переопределение любого другого шаблона в вашем проекте.