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

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

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" 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 Form

Все классы форм создаются как подклассы либо 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 элемента 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 %}

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

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

Если на вашем сайте используется одна и та же логика отображения форм в нескольких местах, вы можете уменьшить дублирование, сохранив цикл формы в отдельном шаблоне и переопределив атрибут формы template_name для отображения формы с использованием пользовательского шаблона. В приведенном ниже примере {{ 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 %}

В вашей форме:

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

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

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

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