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

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

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

HTML-формы

В HTML форма — это набор элементов внутри <form>...</form> , которые позволяют посетителям выполнять такие действия, как ввод текста, выбор параметров, манипулирование объектами или элементами управления и т. д., а затем отправлять эту информацию обратно на сервер.

Некоторые из этих элементов интерфейса формы — текстовые поля или флажки — достаточно просты и встроены в сам HTML. Другие гораздо сложнее; интерфейс, который отображает календарь дат, позволяет перемещать ползунок или манипулировать элементами управления, обычно использует JavaScript и CSS, а также HTML-элементы форм <input> для достижения этих эффектов.

Помимо своих <input> элементов, форма должна указать две вещи:

• где: URL, на который должны возвращаться данные, соответствующие вводу пользователя
• как: HTTP-метод, с помощью которого данные должны возвращаться

Например, форма входа в Django админ-панель содержит несколько <input> элементов: одно type="text" для имени пользователя, одно type="password" для пароля и одно type="submit" для кнопки «Войти». Она также содержит некоторые скрытые текстовые поля, которые пользователь не видит, которые Django использует для определения следующих шагов.

Она также сообщает браузеру, что данные формы должны быть отправлены по URL, указанному в <form> атрибуте action - /admin/ - и что они должны быть отправлены с помощью HTTP-метода, указанного в method атрибуте - post.

Когда элемент <input type="submit" value="Log in"> срабатывает, данные возвращаются в /admin/.

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 в формах

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

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

Django обрабатывает три различные части работы с формами:

• подготовка и переструктурирование данных для подготовки к отображению
• создание HTML-форм для данных
• прием и обработка отправленных форм и данных от клиента

Можно написать код, который выполнит все это вручную, но Django может справиться со всем этим за вас.

Формы в Django

Мы кратко описали HTML-формы, но HTML-<form> — это лишь одна часть необходимой машины.

В контексте веб-приложения «форма» может относиться к этой HTML-<form>, или к Django Form, который ее генерирует, или к структурированным данным, возвращаемым при отправке, или к полному рабочему набору этих частей.

Класс 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>

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

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

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

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

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

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

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

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

Класс Form

Мы уже знаем, как должна выглядеть наша HTML-форма. Наша отправная точка для нее в Django выглядит так:

from django import forms

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

Это определяет класс Form с одним полем (your_name). Мы применили понятную метку к полю, которая будет отображаться в <label> при его рендеринге (хотя в этом случае, указанная нами label фактически совпадает с той, что была бы сгенерирована автоматически, если бы мы её опустили).

Максимальная допустимая длина поля определяется max_length. Это делает два дела. Оно устанавливает maxlength="100" на HTML <input> (так что браузер должен предотвратить ввод пользователем большего числа символов). Это также означает, что когда Django получает форму обратно от браузера, он проверит длину данных.

Экземпляр Form имеет метод is_valid(), который выполняет процедуры проверки для всех его полей. Когда этот метод вызывается, если все поля содержат допустимые данные, он:

• вернёт True
• поместит данные формы в свой атрибут cleaned_data.

Вся форма при первом рендеринге будет выглядеть так:

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

Обратите внимание, что она не включает <form> теги или кнопку отправки. Нам нужно будет предоставить их самим в шаблоне.

Обработка формы в представлении

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

Для обработки формы нам нужно создать её экземпляр в представлении для URL, куда мы хотим её опубликовать:

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

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

Если мы попадем в это представление с запросом GET, оно создаст пустой экземпляр формы и поместит его в контекст шаблона для рендеринга. Именно это произойдет при первом посещении URL.

Если форма отправляется с помощью запроса POST, представление снова создаст экземпляр формы и заполнит его данными из запроса: form = NameForm(request.POST) Это называется «привязкой данных к форме» (теперь это связанная форма).

Мы вызываем метод is_valid() формы; если он не True, мы возвращаемся к шаблону с формой. На этот раз форма уже не пустая (не связанная), поэтому HTML-форма будет заполнена ранее отправленными данными, где ее можно будет отредактировать и исправить по мере необходимости.

Если is_valid() является True, мы теперь сможем найти все валидированные данные формы в её атрибуте cleaned_data. Мы можем использовать эти данные для обновления базы данных или для других операций перед отправкой HTTP-перенаправления браузеру, указывая ему, куда перейти дальше.

Шаблон

Нам не нужно делать много в нашем шаблоне name.html. Простейший пример:

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

Все поля формы и их атрибуты будут распакованы в HTML-разметку из {{ form }} языком шаблонов Django.

Теперь у нас есть работающая веб-форма, описанная Django Form, обработанная представлением и отображённая как HTML <form>.

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

Больше о классах форм Django

Все классы форм создаются как подклассы django.forms.Form, включая ModelForm, который вы встречаете в административной панели Django.

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

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

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

Атрибут 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 — всего лишь три из доступных типов полей; полный список можно найти в Поля формы.

Виджеты

У каждого поля формы есть соответствующий класс виджета, который, в свою очередь, соответствует HTML-виджету формы, например, <input type="text">.

В большинстве случаев у поля будет разумный виджет по умолчанию. Например, по умолчанию у CharField будет виджет TextInput, который создаёт <input type="text"> в HTML. Если вам нужен <textarea> вместо этого, вы укажете соответствующий виджет при определении поля формы, как мы сделали для поля message.

Данные полей

Независимо от данных, отправленных с формой, после успешной проверки, вызвав is_valid() (и is_valid() вернувший True ), проверенные данные формы будут в словаре form.cleaned_data. Эти данные будут аккуратно преобразованы в типы Python для вас.

В примере формы связи выше cc_myself будет булевым значением. Аналогично, поля, такие как IntegerField и FloatField преобразуют значения в Python int и float соответственно.

Вот как данные формы можно обработать в представлении, которое обрабатывает эту форму:

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/')

Некоторые типы полей требуют дополнительной обработки. Например, файлы, загружаемые с помощью формы, должны обрабатываться по-другому (их можно получить из request.FILES, а не из request.POST). Подробную информацию о том, как обрабатывать загрузки файлов с вашей формой, см. в Связывание загруженных файлов с формой.

Работа с шаблонами форм

Для того, чтобы добавить вашу форму в шаблон, просто поместите экземпляр формы в контекст шаблона. Таким образом, если ваша форма называется form в контексте, {{ form }} правильно отобразит её элементы <label> и <input>.

Параметры отображения форм

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

• {{ 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" /></p>
<p><label for="id_message">Message:</label>
    <textarea name="message" id="id_message"></textarea></p>
<p><label for="id_sender">Sender:</label>
    <input type="email" name="sender" id="id_sender" /></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>, к которому ссылается сопровождающий тег метки. Это важно для обеспечения доступности форм для вспомогательных технологий, таких как программы чтения с экрана. Также вы можете настроить способ генерации меток и идентификаторов.

См. Вывод форм в виде 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>

Отображение сообщений об ошибках формы

Конечно, цена этой гибкости — больше работы. До сих пор нам не нужно было беспокоиться о том, как отобразить ошибки формы, потому что за это отвечали мы. В этом примере нам нужно было убедиться, что мы обрабатываем любые ошибки для каждого поля и любые ошибки для формы в целом. Обратите внимание на {{ form.non_field_errors }} в верхней части формы и поиск шаблонов для ошибок каждого поля.

Использование {{ form.name_of_field.errors }} отображает список ошибок формы, отображаемых как маркированный список. Это может выглядеть так:

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

Список имеет CSS-класс errorlist, чтобы вы могли стилизовать его внешний вид. Если вы хотите дополнительно настроить отображение ошибок, вы можете сделать это, перебирая их:

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

Ошибки, не относящиеся к полям (и/или ошибки скрытых полей, которые отображаются в верхней части формы при использовании помощников, таких как form.as_p()), будут отображаться с дополнительным классом nonfield, чтобы отличить их от ошибок, относящихся к конкретным полям. Например, {{ form.non_field_errors }} будет выглядеть так:

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

См. API форм для получения дополнительной информации об ошибках, стилизации и работе с атрибутами форм в шаблонах.

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

Если вы используете один и тот же 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.label }}

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

{{ field.label_tag }}

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

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

{{ field.id_for_label }}

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

{{ field.value }}

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

{{ field.html_name }}

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

{{ field.help_text }}

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

{{ field.errors }}

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

{{ field.is_hidden }}

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

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

{{ field.field }}

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

Перебор скрытых и видимых полей

Если вы вручную выстраиваете форму в шаблоне, а не полагаетесь на стандартный макет Django, вы можете по-разному обращаться со скрытыми <input type="hidden"> полями и нескрываемыми полями. Например, поскольку скрытые поля ничего не отображают, размещение сообщений об ошибках «рядом» с полем может ввести в заблуждение пользователей — поэтому ошибки для таких полей следует обрабатывать иначе.

Django предоставляет два метода для перебора скрытых и видимых полей независимо: hidden_fields() и visible_fields(). Вот модификация предыдущего примера, которая использует эти два метода:

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

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

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

Если ваш сайт использует одну и ту же логику отображения форм в нескольких местах, вы можете уменьшить дублирование, сохранив цикл формы в отдельном шаблоне и используя тег include для его повторного использования в других шаблонах:

# In your form template:
{% include "form_snippet.html" %}

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

Если объект формы, передаваемый в шаблон, имеет другое имя в контексте, вы можете переименовать его, используя аргумент with тега include:

{% include "form_snippet.html" with form=comment_form %}

Если вы часто делаете это, вы можете рассмотреть создание пользовательского тега включения.

Дополнительные темы

Это базовые сведения, но формы могут делать гораздо больше:

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