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

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

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

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

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

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

Указав пользовательский рендерер форм и переопределив form_template_name, вы можете настроить стандартную разметку форм во всём проекте из одного места.

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

Аналогичные принципы применимы к рендерингу наборов форм. Подробнее см. Использование набора форм в представлениях и шаблонах.

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

class BaseRenderer [source]

Базовый класс для встроенных рендереров форм.

form_template_name

Используемое по умолчанию имя шаблона для рендеринга формы.

По умолчанию используется шаблон "django/forms/div.html".

formset_template_name

Используемое по умолчанию имя шаблона для рендеринга набора форм.

По умолчанию используется шаблон "django/forms/formsets/div.html".

field_template_name

Добавлена в Django 5.0.

Используемое по умолчанию имя шаблона для рендеринга BoundField.

По умолчанию используется "django/forms/field.html".

get_template(template_name) [source]

Подклассы должны реализовывать этот метод с соответствующей логикой поиска шаблонов.

render(template_name, context, request=None) [source]

Рендерит указанный шаблон или возбуждает исключение TemplateDoesNotExist.

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

DjangoTemplates

class DjangoTemplates [source]

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

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

class DjangoDivFormRenderer [source]

Псевдоним для DjangoTemplates.

Jinja2

class Jinja2 [source]

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

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

class Jinja2DivFormRenderer [source]

Псевдоним для Jinja2.

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'
  

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

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

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

• formset: экземпляр набора форм.

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

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

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

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

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

• field: BoundField.

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

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

• name
• value
• attrs
• is_hidden
• template_name

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

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

BaseFormSet.template_name

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

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

Form.template_name

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

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

Field.template_name

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

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

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

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