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

Виджеты форм Django рендерятся с помощью системы шаблонов 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

Этот рендер использует автономный движок шаблонов 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'
  

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

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

Шаблоны formset получают контекст от BaseFormSet.get_context(). По умолчанию formset получает словарь со следующими значениями:

• formset: Экземпляр formset.

Контекст, доступный в шаблонах формы

Шаблоны форм получают контекст от Form.get_context(). По умолчанию формы получают словарь со следующими значениями:

• form: Связанная форма.
• fields: Все связанные поля, кроме скрытых.
• hidden_fields: Все связанные скрытые поля.
• errors: Все ошибки формы, не связанные с полями или скрытыми полями.

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

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

• name
• value
• attrs
• is_hidden
• template_name

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

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

BaseFormSet.template_name

Чтобы переопределить шаблоны formset, вы должны использовать рендер TemplatesSetting. Затем переопределение шаблонов виджетов работает так же, как и переопределение любого другого шаблона в вашем проекте.

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

Form.template_name

Чтобы переопределить шаблоны форм, вы должны использовать рендер TemplatesSetting. Затем переопределение шаблонов виджетов работает так же, как и переопределение любого другого шаблона в вашем проекте.

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

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

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