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

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

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

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

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

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

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

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

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

DjangoTemplates

class DjangoTemplates [source]

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

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

Jinja2

class Jinja2 [source]

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

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

TemplatesSetting

class TemplatesSetting [source]

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

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

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

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

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

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

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

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

• name
• value
• attrs
• is_hidden
• template_name

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

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

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

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