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

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

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

С другой стороны, 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" required>

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

Обработка формы

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

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

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

Если мы попадаем в это представление с 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, либо django.forms.ModelForm. Можно представить, что ModelForm является подклассом Form. Form и ModelForm фактически наследуют общие функции от (приватного) класса BaseForm, но эта деталь реализации редко важна.

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

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

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

Атрибут 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" 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>, который используется тегом сопровождающей метки. Это важно для обеспечения доступности форм для вспомогательных технологий, таких как программы чтения с экрана. Вы также можете настроить способ генерации меток и идентификаторов.

См. Вывод форм как 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. Учитывает префикс формы, если он задан.

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