For error in form errors

I’m trying to create a form in Django. That works and all, but I want all the errors to be at the top of the form, not next to each field that has the error. I tried looping over form.errors, but it only showed the name of the field that had an error, not an error message such as «Name is required.»

This is pretty much what I’d like to be able to use at the top of the form:

{% if form.??? %}
    <ul class="errorlist">
    {% for error in form.??? %}
        <li>{{ error }}</li>
    {% endfor %}
    </ul>
{% endif %}

What would I use for ??? there? It’s not errors; that just outputs the names of the fields.

asked Jan 9, 2010 at 22:53

{% for field, errors in form.errors.items %}
    {% for error in errors %}
...

3

{% if form.errors %}
      {% for field in form %}

           {% for error in field.errors %}
                {{field.label}}: {{ error|escape }}
           {% endfor %}

      {% endfor %}
{% endif %}

1

GET и POST¶

GET и POST — единственные методы HTTP, которые следует использовать при работе с формами.

Форма входа в Django возвращается с помощью метода POST, в котором браузер упаковывает данные формы, кодирует их для передачи, отправляет на сервер, а затем получает ответ.

GET, напротив, объединяет предоставленные данные в строку и использует ее для составления URL. URL содержит адрес, по которому должны быть отправлены данные, а также ключи и значения данных. Вы можете увидеть это в действии, если выполните поиск в документации Django, который выдаст URL вида https://docs.djangoproject.com/search/?q=forms&release=1.

GET и POST обычно используются для разных целей.

Любой запрос, который может быть использован для изменения состояния системы — например, запрос, который вносит изменения в базу данных — должен использовать POST. GET следует использовать только для запросов, которые не влияют на состояние системы.

GET также не подходит для формы пароля, поскольку пароль будет отображаться в URL, а значит, и в истории браузера и журналах сервера, причем открытым текстом. Он также не подходит для больших объемов данных или для двоичных данных, таких как изображение. Веб-приложение, использующее запросы GET для административных форм, представляет собой угрозу безопасности: злоумышленнику может быть легко сымитировать запрос формы, чтобы получить доступ к важным частям системы. POST в сочетании с другими средствами защиты, такими как CSRF protection в Django, обеспечивает больший контроль над доступом.

С другой стороны, GET подходит для таких вещей, как форма веб-поиска, потому что URL-адреса, которые представляют запрос GET, можно легко добавить в закладки, поделиться ими или отправить повторно.

Класс Django Form¶

В основе этой системы компонентов лежит класс Django Form. Точно так же, как модель Django описывает логическую структуру объекта, его поведение и то, как его части представлены нам, класс Form описывает форму и определяет, как она работает и отображается.

Подобно тому, как поля класса модели отображаются на поля базы данных, поля класса формы отображаются на элементы HTML-формы <input>. (Поле ModelForm отображает поля класса модели на элементы HTML-формы <input> через Form; на этом основана админка Django).

Поля формы сами по себе являются классами; они управляют данными формы и выполняют проверку при отправке формы. DateField и FileField обрабатывают совершенно разные типы данных и должны делать с ними разные вещи.

Поле формы представляется пользователю в браузере как HTML «виджет» — часть пользовательского интерфейса. Каждый тип поля имеет соответствующее значение по умолчанию Widget class, но оно может быть переопределено по мере необходимости.

Создание, обработка и визуализация форм¶

При визуализации объекта в Django мы обычно:

1. получить его в представлении (например, получить его из базы данных)
2. передать его в контекст шаблона
3. развернуть его в HTML-разметку с помощью переменных шаблона

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

В случае экземпляра модели, не содержащего данных, редко, если вообще когда-либо, будет полезно что-то делать с ним в шаблоне. С другой стороны, имеет смысл отобразить незаполненную форму — именно это мы делаем, когда хотим, чтобы пользователь заполнил ее.

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

Когда мы создаем форму, мы можем оставить ее пустой или предварительно заполнить, например, с помощью:

• данные из сохраненного экземпляра модели (как в случае с админскими формами для редактирования)
• данные, которые мы собрали из других источников
• данные, полученные от предыдущей отправки HTML-формы

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

Работа, которую необходимо выполнить¶

Предположим, вы хотите создать простую форму на своем сайте, чтобы получить имя пользователя. Вам понадобится что-то подобное в вашем шаблоне:

<form action="/your-name/" method="post">
    <label for="your_name">Your name: </label>
    <input id="your_name" type="text" name="your_name" value="{{ current_name }}">
    <input type="submit" value="OK">
</form>

Это указывает браузеру вернуть данные формы в URL /your-name/, используя метод POST. Он отобразит текстовое поле с надписью «Ваше имя:» и кнопку с надписью «OK». Если контекст шаблона содержит переменную current_name, она будет использована для предварительного заполнения поля your_name.

Вам понадобится представление, которое отображает шаблон, содержащий HTML-форму, и которое может предоставлять поле current_name по мере необходимости.

Когда форма отправлена, запрос POST, который отправляется на сервер, будет содержать данные формы.

Теперь вам также понадобится представление, соответствующее этому URL /your-name/, которое будет находить соответствующие пары ключ/значение в запросе, а затем обрабатывать их.

Это очень простая форма. На практике форма может содержать десятки или сотни полей, многие из которых должны быть предварительно заполнены, и мы можем ожидать, что пользователь пройдет цикл редактирования-отправки несколько раз, прежде чем завершит операцию.

Мы можем потребовать некоторой проверки в браузере, даже до отправки формы; мы можем захотеть использовать гораздо более сложные поля, которые позволят пользователю делать такие вещи, как выбор даты из календаря и так далее.

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

Создание формы в Django¶

from django import forms

class NameForm(forms.Form):
    your_name = forms.CharField(label='Your name', max_length=100)

<label for="your_name">Your name: </label>
<input id="your_name" type="text" name="your_name" maxlength="100" required>

from django.http import HttpResponseRedirect
from django.shortcuts import render

from .forms import NameForm

def get_name(request):
    # if this is a POST request we need to process the form data
    if request.method == 'POST':
        # create a form instance and populate it with data from the request:
        form = NameForm(request.POST)
        # check whether it's valid:
        if form.is_valid():
            # process the data in form.cleaned_data as required
            # ...
            # redirect to a new URL:
            return HttpResponseRedirect('/thanks/')

    # if a GET (or any other method) we'll create a blank form
    else:
        form = NameForm()

    return render(request, 'name.html', {'form': form})

<form action="/your-name/" method="post">
    {% csrf_token %}
    {{ form }}
    <input type="submit" value="Submit">
</form>

Модели и формы

На самом деле, если ваша форма будет использоваться для прямого добавления или редактирования модели Django, ModelForm может сэкономить вам много времени, усилий и кода, потому что она создаст форму, вместе с соответствующими полями и их атрибутами, из класса Model.

Связанные и несвязанные экземпляры форм¶

Различие между Связанные и несвязанные формы является важным:

• Несвязанная форма не имеет данных, связанных с ней. При отображении пользователю она будет пустой или будет содержать значения по умолчанию.
• Связанная форма содержит отправленные данные и, следовательно, может быть использована для определения того, являются ли эти данные действительными. Если отображается недействительная связанная форма, она может содержать встроенные сообщения об ошибках, сообщающие пользователю, какие данные необходимо исправить.

Атрибут формы is_bound подскажет вам, есть ли у формы данные, привязанные к ней, или нет.

Подробнее о полях¶

Рассмотрим более полезную форму, чем наш минимальный пример выше, которую мы могли бы использовать для реализации функции «свяжитесь со мной» на персональном сайте:

from django import forms

class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    message = forms.CharField(widget=forms.Textarea)
    sender = forms.EmailField()
    cc_myself = forms.BooleanField(required=False)

В нашей предыдущей форме использовалось одно поле, your_name, a CharField. В данном случае наша форма имеет четыре поля: subject, message, sender и cc_myself. CharField, EmailField и BooleanField — это только три из доступных типов полей; полный список можно найти в Поля формы.

from django.core.mail import send_mail

if form.is_valid():
    subject = form.cleaned_data['subject']
    message = form.cleaned_data['message']
    sender = form.cleaned_data['sender']
    cc_myself = form.cleaned_data['cc_myself']

    recipients = ['info@example.com']
    if cc_myself:
        recipients.append(sender)

    send_mail(subject, message, sender, recipients)
    return HttpResponseRedirect('/thanks/')

Дополнительная мебель для шаблонов форм

Не забывайте, что вывод формы не включает окружающие теги <form> или элемент управления формы submit. Вы должны будете предоставить их сами.

Многоразовые шаблоны форм¶

HTML-вывод при отображении формы генерируется с помощью шаблона. Вы можете управлять этим, создав соответствующий файл шаблона и установив пользовательский FORM_RENDERER для использования этого form_template_name в масштабах всего сайта. Вы также можете настраивать отдельные формы, переопределяя атрибут template_name формы для вывода формы с использованием пользовательского шаблона, или передавая имя шаблона непосредственно в Form.render().

Приведенный ниже пример приведет к тому, что {{ form }} будет выведен как вывод шаблона form_snippet.html.

В ваших шаблонах:

# In your template:
{{ form }}

# In form_snippet.html:
{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}

Затем вы можете настроить параметры FORM_RENDERER:

from django.forms.renderers import TemplatesSetting

class CustomFormRenderer(TemplatesSetting):
    form_template_name = "form_snippet.html"

FORM_RENDERER = "project.settings.CustomFormRenderer"

… или для одной формы:

class MyForm(forms.Form):
    template_name = "form_snippet.html"
    ...

… или для одного рендера экземпляра формы, передавая имя шаблона в Form.render(). Вот пример использования этого в представлении:

def index(request):
    form = MyForm()
    rendered_form = form.render("form_snippet.html")
    context = {'form': rendered_form}
    return render(request, 'index.html', context)

Более подробную информацию см. в разделе Вывод форм в формате HTML.

Параметры рендеринга формы¶

Однако для пар <label>/<input> существуют и другие варианты вывода:

• {{ form.as_div }} будет отображать их обернутыми в теги <div>.
• {{ form.as_table }} будет отображать их как ячейки таблицы, обернутые в теги <tr>.
• {{ form.as_p }} будет отображать их обернутыми в теги <p>.
• {{ form.as_ul }} будет отображать их обернутыми в теги <li>.

Обратите внимание, что вам придется самостоятельно предоставить окружающие элементы <table> или <ul>.

Вот вывод {{ form.as_p }} для нашего экземпляра ContactForm:

<p><label for="id_subject">Subject:</label>
    <input id="id_subject" type="text" name="subject" maxlength="100" required></p>
<p><label for="id_message">Message:</label>
    <textarea name="message" id="id_message" required></textarea></p>
<p><label for="id_sender">Sender:</label>
    <input type="email" name="sender" id="id_sender" required></p>
<p><label for="id_cc_myself">Cc myself:</label>
    <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>

Обратите внимание, что каждое поле формы имеет атрибут ID, установленный в id_<field-name>, на который ссылается сопровождающий тег label. Это важно для обеспечения доступности форм для вспомогательных технологий, таких как программы для чтения с экрана. Вы также можете customize the way in which labels and ids are generated.

Подробнее об этом см. в разделе Вывод форм в формате HTML.

Рендеринг полей вручную¶

Нам не обязательно позволять Django распаковывать поля формы; при желании мы можем сделать это вручную (что позволит нам, например, изменить порядок полей). Каждое поле доступно как атрибут формы с помощью {{ form.name_of_field }}, и в шаблоне Django будет отображаться соответствующим образом. Например:

{{ form.non_field_errors }}
<div class="fieldWrapper">
    {{ form.subject.errors }}
    <label for="{{ form.subject.id_for_label }}">Email subject:</label>
    {{ form.subject }}
</div>
<div class="fieldWrapper">
    {{ form.message.errors }}
    <label for="{{ form.message.id_for_label }}">Your message:</label>
    {{ form.message }}
</div>
<div class="fieldWrapper">
    {{ form.sender.errors }}
    <label for="{{ form.sender.id_for_label }}">Your email address:</label>
    {{ form.sender }}
</div>
<div class="fieldWrapper">
    {{ form.cc_myself.errors }}
    <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>
    {{ form.cc_myself }}
</div>

Полные элементы <label> также могут быть сгенерированы с помощью label_tag(). Например:

<div class="fieldWrapper">
    {{ form.subject.errors }}
    {{ form.subject.label_tag }}
    {{ form.subject }}
</div>

<ul class="errorlist">
    <li>Sender is required.</li>
</ul>

{% if form.subject.errors %}
    <ol>
    {% for error in form.subject.errors %}
        <li><strong>{{ error|escape }}</strong></li>
    {% endfor %}
    </ol>
{% endif %}

<ul class="errorlist nonfield">
    <li>Generic validation error</li>
</ul>

Перебор полей формы¶

Если вы используете один и тот же HTML для каждого из полей формы, вы можете уменьшить количество дублирующегося кода, перебирая каждое поле по очереди с помощью цикла {% for %}:

{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
        {% if field.help_text %}
        <p class="help">{{ field.help_text|safe }}</p>
        {% endif %}
    </div>
{% endfor %}

Полезные атрибуты на {{ field }} включают:

{{ field.errors }}

Выводит <ul class="errorlist">, содержащий все ошибки валидации, соответствующие данному полю. Вы можете настроить представление ошибок с помощью цикла {% for error in field.errors %}. В этом случае каждый объект в цикле представляет собой строку, содержащую сообщение об ошибке.

{{ field.field }}

Экземпляр Field из класса формы, который обернут этим BoundField. Вы можете использовать его для доступа к атрибутам Field, например, {{ char_field.field.max_length }}.

{{ field.help_text }}

Любой текст справки, связанный с полем.

{{ field.html_name }}

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

{{ field.id_for_label }}

ID, который будет использоваться для этого поля (id_email в примере выше). Если вы создаете метку вручную, вы можете использовать этот параметр вместо label_tag. Это также полезно, например, если у вас есть встроенный JavaScript и вы хотите избежать жесткого кодирования ID поля.

{{ field.is_hidden }}

Этот атрибут имеет значение True, если поле формы является скрытым полем, и False в противном случае. Он не особенно полезен в качестве переменной шаблона, но может быть полезен в условных тестах, таких как:

{% if field.is_hidden %}
   {# Do something special #}
{% endif %}

{{ field.label }}

Метка поля, например, Email address.

{{ field.label_tag }}

Метка поля, обернутая в соответствующий тег HTML <label>. Это включает в себя label_suffix формы. Например, по умолчанию label_suffix — это двоеточие:

<label for="id_email">Email address:</label>

{{ field.legend_tag }}

New in Django 4.1.

Аналогичен field.label_tag, но использует тег <legend> вместо <label>, для виджетов с несколькими входами, обернутыми в <fieldset>.

{{ field.use_fieldset }}

New in Django 4.1.

Этот атрибут True, если виджет поля формы содержит несколько входов, которые должны быть семантически сгруппированы в <fieldset> с <legend> для улучшения доступности. Пример использования в шаблоне:

{% if field.use_fieldset %}
  <fieldset>
  {% if field.label %}{{ field.legend_tag }}{% endif %}
{% else %}
  {% if field.label %}{{ field.label_tag }}{% endif %}
{% endif %}
{{ field }}
{% if field.use_fieldset %}</fieldset>{% endif %}

{{ field.value }}

Значение поля. например, someone@example.com.

• Формсеты
  • Использование исходных данных с помощью набора форм
  • Ограничение максимального количества форм
  • Ограничение максимального количества инстанцированных форм
  • Валидация форм
  • Проверка количества форм в наборе форм
  • Работа с заказами и удалением форм
  • Добавление дополнительных полей в набор форм
  • Передача пользовательских параметров формам набора форм
  • Настройка префикса набора форм
  • Использование набора форм в представлениях и шаблонах
• Создание форм из моделей
  • ModelForm
  • Модельные наборы форм
  • Встроенные наборы форм
• Активы формы (класс Media)
  • Активы как статическое определение
  • Media как динамическое свойство
  • Пути в определениях активов
  • Media объекты
  • Media на формах

См.также

The Forms Reference

Охватывает полный справочник API, включая поля форм, виджеты форм, а также валидацию форм и полей.

Review Date

2020-06-15

Reviewed Item

Django Forms | Custom Form Validations

Author Rating

5

Software Name

Django Web Framework

Software Name

Windows Os, Mac Os, Ubuntu Os

Software Category

Web Development

GET and POST¶

GET and POST are the only HTTP methods to use when dealing with forms.

Django’s login form is returned using the POST method, in which the browser
bundles up the form data, encodes it for transmission, sends it to the server,
and then receives back its response.

GET, by contrast, bundles the submitted data into a string, and uses this
to compose a URL. The URL contains the address where the data must be sent, as
well as the data keys and values. You can see this in action if you do a search
in the Django documentation, which will produce a URL of the form
https://docs.djangoproject.com/search/?q=forms&release=1.

GET and POST are typically used for different purposes.

Any request that could be used to change the state of the system — for example,
a request that makes changes in the database — should use POST. GET
should be used only for requests that do not affect the state of the system.

GET would also be unsuitable for a password form, because the password
would appear in the URL, and thus, also in browser history and server logs,
all in plain text. Neither would it be suitable for large quantities of data,
or for binary data, such as an image. A web application that uses GET
requests for admin forms is a security risk: it can be easy for an attacker to
mimic a form’s request to gain access to sensitive parts of the system.
POST, coupled with other protections like Django’s CSRF protection offers more control over access.

On the other hand, GET is suitable for things like a web search form,
because the URLs that represent a GET request can easily be bookmarked,
shared, or resubmitted.

The Django Form class¶

At the heart of this system of components is Django’s Form class. In
much the same way that a Django model describes the logical structure of an
object, its behavior, and the way its parts are represented to us, a
Form class describes a form and determines how it works and appears.

In a similar way that a model class’s fields map to database fields, a form
class’s fields map to HTML form <input> elements. (A ModelForm
maps a model class’s fields to HTML form <input> elements via a
Form; this is what the Django admin is based upon.)

A form’s fields are themselves classes; they manage form data and perform
validation when a form is submitted. A DateField and a
FileField handle very different kinds of data and have to do
different things with it.

A form field is represented to a user in the browser as an HTML “widget” — a
piece of user interface machinery. Each field type has an appropriate default
Widget class, but these can be overridden as
required.

Instantiating, processing, and rendering forms¶

When rendering an object in Django, we generally:

1. get hold of it in the view (fetch it from the database, for example)
2. pass it to the template context
3. expand it to HTML markup using template variables

Rendering a form in a template involves nearly the same work as rendering any
other kind of object, but there are some key differences.

In the case of a model instance that contained no data, it would rarely if ever
be useful to do anything with it in a template. On the other hand, it makes
perfect sense to render an unpopulated form — that’s what we do when we want
the user to populate it.

So when we handle a model instance in a view, we typically retrieve it from the
database. When we’re dealing with a form we typically instantiate it in the
view.

When we instantiate a form, we can opt to leave it empty or prepopulate it, for
example with:

• data from a saved model instance (as in the case of admin forms for editing)
• data that we have collated from other sources
• data received from a previous HTML form submission

The last of these cases is the most interesting, because it’s what makes it
possible for users not just to read a website, but to send information back
to it too.

The work that needs to be done¶

Suppose you want to create a simple form on your website, in order to obtain
the user’s name. You’d need something like this in your template:

<form action="/your-name/" method="post">
    <label for="your_name">Your name: </label>
    <input id="your_name" type="text" name="your_name" value="{{ current_name }}">
    <input type="submit" value="OK">
</form>

This tells the browser to return the form data to the URL /your-name/, using
the POST method. It will display a text field, labeled “Your name:”, and a
button marked “OK”. If the template context contains a current_name
variable, that will be used to pre-fill the your_name field.

You’ll need a view that renders the template containing the HTML form, and
that can supply the current_name field as appropriate.

When the form is submitted, the POST request which is sent to the server
will contain the form data.

Now you’ll also need a view corresponding to that /your-name/ URL which will
find the appropriate key/value pairs in the request, and then process them.

This is a very simple form. In practice, a form might contain dozens or
hundreds of fields, many of which might need to be prepopulated, and we might
expect the user to work through the edit-submit cycle several times before
concluding the operation.

We might require some validation to occur in the browser, even before the form
is submitted; we might want to use much more complex fields, that allow the
user to do things like pick dates from a calendar and so on.

At this point it’s much easier to get Django to do most of this work for us.

Building a form in Django¶

from django import forms

class NameForm(forms.Form):
    your_name = forms.CharField(label='Your name', max_length=100)

<label for="your_name">Your name: </label>
<input id="your_name" type="text" name="your_name" maxlength="100" required>

from django.http import HttpResponseRedirect
from django.shortcuts import render

from .forms import NameForm

def get_name(request):
    # if this is a POST request we need to process the form data
    if request.method == 'POST':
        # create a form instance and populate it with data from the request:
        form = NameForm(request.POST)
        # check whether it's valid:
        if form.is_valid():
            # process the data in form.cleaned_data as required
            # ...
            # redirect to a new URL:
            return HttpResponseRedirect('/thanks/')

    # if a GET (or any other method) we'll create a blank form
    else:
        form = NameForm()

    return render(request, 'name.html', {'form': form})

<form action="/your-name/" method="post">
    {% csrf_token %}
    {{ form }}
    <input type="submit" value="Submit">
</form>

Models and Forms

In fact if your form is going to be used to directly add or edit a Django
model, a ModelForm can save you a great
deal of time, effort, and code, because it will build a form, along with the
appropriate fields and their attributes, from a Model class.

Bound and unbound form instances¶

The distinction between Bound and unbound forms is important:

• An unbound form has no data associated with it. When rendered to the user,
  it will be empty or will contain default values.
• A bound form has submitted data, and hence can be used to tell if that data
  is valid. If an invalid bound form is rendered, it can include inline error
  messages telling the user what data to correct.

The form’s is_bound attribute will tell you whether a form has
data bound to it or not.

More on fields¶

Consider a more useful form than our minimal example above, which we could use
to implement “contact me” functionality on a personal website:

from django import forms

class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    message = forms.CharField(widget=forms.Textarea)
    sender = forms.EmailField()
    cc_myself = forms.BooleanField(required=False)

Our earlier form used a single field, your_name, a CharField. In
this case, our form has four fields: subject, message, sender and
cc_myself. CharField, EmailField and
BooleanField are just three of the available field types; a full list
can be found in Form fields.

from django.core.mail import send_mail

if form.is_valid():
    subject = form.cleaned_data['subject']
    message = form.cleaned_data['message']
    sender = form.cleaned_data['sender']
    cc_myself = form.cleaned_data['cc_myself']

    recipients = ['info@example.com']
    if cc_myself:
        recipients.append(sender)

    send_mail(subject, message, sender, recipients)
    return HttpResponseRedirect('/thanks/')

Additional form template furniture

Don’t forget that a form’s output does not include the surrounding
<form> tags, or the form’s submit control. You will have to provide
these yourself.

Reusable form templates¶

The HTML output when rendering a form is itself generated via a template. You
can control this by creating an appropriate template file and setting a custom
FORM_RENDERER to use that
form_template_name site-wide. You
can also customize per-form by overriding the form’s
template_name attribute to render the form using the
custom template, or by passing the template name directly to
Form.render().

The example below will result in {{ form }} being rendered as the output of
the form_snippet.html template.

In your templates:

# In your template:
{{ form }}

# In form_snippet.html:
{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}

Then you can configure the FORM_RENDERER setting:

from django.forms.renderers import TemplatesSetting

class CustomFormRenderer(TemplatesSetting):
    form_template_name = "form_snippet.html"

FORM_RENDERER = "project.settings.CustomFormRenderer"

… or for a single form:

class MyForm(forms.Form):
    template_name = "form_snippet.html"
    ...

… or for a single render of a form instance, passing in the template name to
the Form.render(). Here’s an example of this being used in a view:

def index(request):
    form = MyForm()
    rendered_form = form.render("form_snippet.html")
    context = {'form': rendered_form}
    return render(request, 'index.html', context)

See Outputting forms as HTML for more details.

Form rendering options¶

There are other output options though for the <label>/<input> pairs:

• {{ form.as_div }} will render them wrapped in <div> tags.
• {{ form.as_table }} will render them as table cells wrapped in <tr>
  tags.
• {{ form.as_p }} will render them wrapped in <p> tags.
• {{ form.as_ul }} will render them wrapped in <li> tags.

Note that you’ll have to provide the surrounding <table> or <ul>
elements yourself.

Here’s the output of {{ form.as_p }} for our ContactForm instance:

<p><label for="id_subject">Subject:</label>
    <input id="id_subject" type="text" name="subject" maxlength="100" required></p>
<p><label for="id_message">Message:</label>
    <textarea name="message" id="id_message" required></textarea></p>
<p><label for="id_sender">Sender:</label>
    <input type="email" name="sender" id="id_sender" required></p>
<p><label for="id_cc_myself">Cc myself:</label>
    <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>

Note that each form field has an ID attribute set to id_<field-name>, which
is referenced by the accompanying label tag. This is important in ensuring that
forms are accessible to assistive technology such as screen reader software.
You can also customize the way in which labels and ids are generated.

See Outputting forms as HTML for more on this.

Rendering fields manually¶

We don’t have to let Django unpack the form’s fields; we can do it manually if
we like (allowing us to reorder the fields, for example). Each field is
available as an attribute of the form using {{ form.name_of_field }}, and
in a Django template, will be rendered appropriately. For example:

{{ form.non_field_errors }}
<div class="fieldWrapper">
    {{ form.subject.errors }}
    <label for="{{ form.subject.id_for_label }}">Email subject:</label>
    {{ form.subject }}
</div>
<div class="fieldWrapper">
    {{ form.message.errors }}
    <label for="{{ form.message.id_for_label }}">Your message:</label>
    {{ form.message }}
</div>
<div class="fieldWrapper">
    {{ form.sender.errors }}
    <label for="{{ form.sender.id_for_label }}">Your email address:</label>
    {{ form.sender }}
</div>
<div class="fieldWrapper">
    {{ form.cc_myself.errors }}
    <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>
    {{ form.cc_myself }}
</div>

Complete <label> elements can also be generated using the
label_tag(). For example:

<div class="fieldWrapper">
    {{ form.subject.errors }}
    {{ form.subject.label_tag }}
    {{ form.subject }}
</div>

<ul class="errorlist">
    <li>Sender is required.</li>
</ul>

{% if form.subject.errors %}
    <ol>
    {% for error in form.subject.errors %}
        <li><strong>{{ error|escape }}</strong></li>
    {% endfor %}
    </ol>
{% endif %}

<ul class="errorlist nonfield">
    <li>Generic validation error</li>
</ul>

Looping over the form’s fields¶

If you’re using the same HTML for each of your form fields, you can reduce
duplicate code by looping through each field in turn using a {% for %}
loop:

{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
        {% if field.help_text %}
        <p class="help">{{ field.help_text|safe }}</p>
        {% endif %}
    </div>
{% endfor %}

Useful attributes on {{ field }} include:

{{ field.errors }}

Outputs a <ul class="errorlist"> containing any validation errors
corresponding to this field. You can customize the presentation of
the errors with a {% for error in field.errors %} loop. In this
case, each object in the loop is a string containing the error message.

{{ field.field }}

The Field instance from the form class that
this BoundField wraps. You can use it to access
Field attributes, e.g.
{{ char_field.field.max_length }}.

{{ field.help_text }}

Any help text that has been associated with the field.

{{ field.html_name }}

The name of the field that will be used in the input element’s name
field. This takes the form prefix into account, if it has been set.

{{ field.id_for_label }}

The ID that will be used for this field (id_email in the example
above). If you are constructing the label manually, you may want to use
this in lieu of label_tag. It’s also useful, for example, if you have
some inline JavaScript and want to avoid hardcoding the field’s ID.

{{ field.is_hidden }}

This attribute is True if the form field is a hidden field and
False otherwise. It’s not particularly useful as a template
variable, but could be useful in conditional tests such as:

{% if field.is_hidden %}
   {# Do something special #}
{% endif %}

{{ field.label }}

The label of the field, e.g. Email address.

{{ field.label_tag }}

The field’s label wrapped in the appropriate HTML <label> tag. This
includes the form’s label_suffix. For example,
the default label_suffix is a colon:

<label for="id_email">Email address:</label>

{{ field.legend_tag }}

New in Django 4.1.

Similar to field.label_tag but uses a <legend> tag in place of
<label>, for widgets with multiple inputs wrapped in a <fieldset>.

{{ field.use_fieldset }}

New in Django 4.1.

This attribute is True if the form field’s widget contains multiple
inputs that should be semantically grouped in a <fieldset> with a
<legend> to improve accessibility. An example use in a template:

{% if field.use_fieldset %}
  <fieldset>
  {% if field.label %}{{ field.legend_tag }}{% endif %}
{% else %}
  {% if field.label %}{{ field.label_tag }}{% endif %}
{% endif %}
{{ field }}
{% if field.use_fieldset %}</fieldset>{% endif %}

{{ field.value }}

The value of the field. e.g someone@example.com.

• Formsets
  • Using initial data with a formset
  • Limiting the maximum number of forms
  • Limiting the maximum number of instantiated forms
  • Formset validation
  • Validating the number of forms in a formset
  • Dealing with ordering and deletion of forms
  • Adding additional fields to a formset
  • Passing custom parameters to formset forms
  • Customizing a formset’s prefix
  • Using a formset in views and templates
• Creating forms from models
  • ModelForm
  • Model formsets
  • Inline formsets
• Form Assets (the Media class)
  • Assets as a static definition
  • Media as a dynamic property
  • Paths in asset definitions
  • Media objects
  • Media on Forms

See also

The Forms Reference

Covers the full API reference, including form fields, form widgets,
and form and field validation.