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

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

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 и вы хотите избежать жесткой кодировки идентификатора поля.

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