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