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