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

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

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

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

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/forms/div.html".

formset_template_name

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

По умолчанию используется шаблон "django/forms/formsets/div.html".

field_template_name

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

По умолчанию имя шаблона для рендеринга BoundField.

По умолчанию используется "django/forms/field.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.

Jinja2

class Jinja2

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

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

class Jinja2DivFormRenderer

Псевдоним для Jinja2.

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: Все ошибки формы, не связанные с полями или скрытыми полями.

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

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

• field: BoundField.

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

Шаблоны виджетов получают контекст от 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. Затем переопределение шаблонов форм происходит так же, как переопределение любого другого шаблона в вашем проекте.

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

Field.template_name

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

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

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

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