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

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

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

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

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

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

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

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

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

DjangoTemplates

class DjangoTemplates

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

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

Jinja2

class Jinja2

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

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

TemplatesSetting

class TemplatesSetting

Этот рендерер предоставляет полный контроль над тем, как берутся шаблоны виджетов. Он использует 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. Тогда переопределение шаблонов виджетов работает так же, как и переопределение любого другого шаблона в вашем проекте.