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

Виджеты форм Django отображаются с помощью template engines system.

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

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

Низкоуровневый API рендеринга

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

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

Используйте один из built-in template form renderers или реализуйте свой собственный. Пользовательские рендереры должны реализовать метод 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[исходный код]

This renderer gives you complete control of how form and widget templates are sourced. It uses get_template() to find templates based on what’s configured in the TEMPLATES setting.

Using this renderer along with the built-in templates requires either:

  • 'django.forms' в INSTALLED_APPS и по крайней мере один двигатель с APP_DIRS=True.

  • Adding the built-in templates directory in DIRS of one of your template engines. To generate that path:

    import django
django.__path__[0] + '/forms/templates'  # or '/forms/jinja2'

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

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

New in Django 4.0.

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

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

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

New in Django 4.0.

Шаблоны форм получают контекст из 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'] для целей зацикливания.

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

New in Django 4.0.

BaseFormSet.template_name

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

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

New in Django 4.0.

Form.template_name

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

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

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

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

Функции набора форм
Виджеты
Вернуться на верх