Работа с формами

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 в Django, обеспечивает больший контроль над доступом.

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

Класс Django Form

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

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

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

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

Создание, обработка и рендеринг форм

При рендеринге объекта в 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>

Это сообщает браузеру вернуть данные формы по адресу /your-name/, используя метод POST. Он отобразит текстовое поле с меткой «Ваше имя:» и кнопку «ОК». Если контекст шаблона содержит переменную 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>

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

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

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

Атрибут формы 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, 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/")

Многократно используемые шаблоны форм

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 для получения более подробной информации.

Многократно используемые шаблоны групп полей

Каждое поле доступно в качестве атрибута формы, используя {{ form.name_of_field }} в шаблоне. У поля есть метод as_field_group(), который отображает связанные элементы поля как группу, его метку, виджет, ошибки и подсказку.

Это позволяет создавать универсальные шаблоны, которые организуют элементы полей в нужном макете. Например:

{{ form.non_field_errors }}
<div class="fieldWrapper">
  {{ form.subject.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.message.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.sender.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.cc_myself.as_field_group }}
</div>

По умолчанию Django использует шаблон "django/forms/field.html", предназначенный для использования со стилем формы по умолчанию "django/forms/div.html".

Шаблон по умолчанию можно настроить, установив field_template_name в параметре FORM_RENDERER вашего проекта:

from django.forms.renderers import TemplatesSetting


class CustomFormRenderer(TemplatesSetting):
    field_template_name = "field_snippet.html"

… или для отдельного поля:

class MyForm(forms.Form):
    subject = forms.CharField(template_name="my_custom_template.html")
    ...

… или в режиме реального времени, вызвав BoundField.render() и указав имя шаблона:

def index(request):
    form = ContactForm()
    subject = form["subject"]
    context = {"subject": subject.render("my_custom_template.html")}
    return render(request, "index.html", context)

Вручную отображать поля

Доступен более точный контроль над отображением полей. Вероятно, это будет в пользовательском шаблоне поля, чтобы шаблон можно было написать один раз и использовать для каждого поля. Однако к нему также можно напрямую получить доступ из атрибута поля в форме. Например:

{{ 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" id="{{ field.auto_id }}_helptext">
            {{ 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_email в примере выше). Если вы вручную создаете метку, вы можете использовать её вместо label_tag. Это также полезно, например, если у вас есть какой-то встроенный JavaScript и вы хотите избежать жёсткого кодирования идентификатора поля.

{{ 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 }}

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

{{ field.use_fieldset }}

Этот атрибут равен 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.

{# Include the hidden fields #}
{% for hidden in form.hidden_fields %}
{{ hidden }}
{% endfor %}
{# Include the visible fields #}
{% for field in form.visible_fields %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}