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[исходный код]

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

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