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