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

Виджеты форм Django рендерятся с использованием системы движков шаблонов Django.

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

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

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

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

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

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

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

Используйте один из встроенных рендереров шаблонов форм или реализуйте свой собственный. Пользовательские рендеры должны реализовывать метод 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/default.html".

formset_template_name

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

Умолчательное имя шаблона для рендеринга formset.

По умолчанию "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'
  

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

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

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

• formset: Экземпляр 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. После этого переопределение шаблонов виджетов работает так же, как переопределение любого другого шаблона в вашем проекте.

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

Form.template_name

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

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

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

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