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

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

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

Класс Django Form¶

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

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

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

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

Создание, обработка и визуализация форм¶

При визуализации объекта в 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. Он отобразит текстовое поле с надписью «Ваше имя:» и кнопку с надписью «OK». Если контекст шаблона содержит переменную current_name, она будет использована для предварительного заполнения поля your_name.

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

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

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

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

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

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

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

from django import forms


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

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

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

from .forms import NameForm


def get_name(request):
    # if this is a POST request we need to process the form data
    if request.method == "POST":
        # create a form instance and populate it with data from the request:
        form = NameForm(request.POST)
        # check whether it's valid:
        if form.is_valid():
            # process the data in form.cleaned_data as required
            # ...
            # redirect to a new URL:
            return HttpResponseRedirect("/thanks/")

    # if a GET (or any other method) we'll create a blank form
    else:
        form = NameForm()

    return render(request, "name.html", {"form": form})

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

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

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

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

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

Подробнее о полях¶

Рассмотрим более полезную форму, чем наш минимальный пример выше, которую мы могли бы использовать для реализации функции «свяжитесь со мной» на персональном сайте:

from django import forms


class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    message = forms.CharField(widget=forms.Textarea)
    sender = forms.EmailField()
    cc_myself = forms.BooleanField(required=False)

В нашей предыдущей форме использовалось одно поле, your_name, a CharField. В данном случае наша форма имеет четыре поля: subject, message, sender и cc_myself. CharField, EmailField и BooleanField - это только три из доступных типов полей; полный список можно найти в Поля формы.

from django.core.mail import send_mail

if form.is_valid():
    subject = form.cleaned_data["subject"]
    message = form.cleaned_data["message"]
    sender = form.cleaned_data["sender"]
    cc_myself = form.cleaned_data["cc_myself"]

    recipients = ["info@example.com"]
    if cc_myself:
        recipients.append(sender)

    send_mail(subject, message, sender, recipients)
    return HttpResponseRedirect("/thanks/")

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

HTML-вывод при отображении формы генерируется с помощью шаблона. Вы можете управлять этим, создав соответствующий файл шаблона и установив пользовательский FORM_RENDERER для использования этого form_template_name в масштабах всего сайта. Вы также можете настраивать отдельные формы, переопределяя атрибут template_name формы для вывода формы с использованием пользовательского шаблона, или передавая имя шаблона непосредственно в Form.render().

Приведенный ниже пример приведет к тому, что {{ form }} будет выведен как вывод шаблона form_snippet.html.

В ваших шаблонах:

# In your template:
{{ form }}

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

Затем вы можете настроить параметры FORM_RENDERER:

from django.forms.renderers import TemplatesSetting


class CustomFormRenderer(TemplatesSetting):
    form_template_name = "form_snippet.html"


FORM_RENDERER = "project.settings.CustomFormRenderer"

… или для одной формы:

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

… или для одного рендера экземпляра формы, передавая имя шаблона в Form.render(). Вот пример использования этого в представлении:

def index(request):
    form = MyForm()
    rendered_form = form.render("form_snippet.html")
    context = {"form": rendered_form}
    return render(request, "index.html", context)

Более подробную информацию см. в разделе Вывод форм в формате HTML.

Параметры рендеринга формы¶

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

• {{ form.as_div }} будет отображать их обернутыми в теги <div>.
• {{ 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>, на который ссылается сопровождающий тег label. Это важно для обеспечения доступности форм для вспомогательных технологий, таких как программы для чтения с экрана. Вы также можете customize the way in which labels and ids are generated.

Подробнее об этом см. в разделе Вывод форм в формате 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>

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

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

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

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

Если вы используете один и тот же HTML для каждого из полей формы, вы можете уменьшить количество дублирующегося кода, перебирая каждое поле по очереди с помощью цикла {% for %}:

{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
        {% if field.help_text %}
        <p class="help">{{ field.help_text|safe }}</p>
        {% endif %}
    </div>
{% endfor %}

Полезные атрибуты на {{ field }} включают:

{{ field.errors }}

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

{{ field.field }}

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

{{ field.help_text }}

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

{{ field.html_name }}

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

{{ field.id_for_label }}

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

{{ field.is_hidden }}

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

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

{{ field.label }}

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

{{ field.label_tag }}

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

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

{{ field.legend_tag }}

New in Django 4.1.

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

{{ field.use_fieldset }}

New in Django 4.1.

Этот атрибут True, если виджет поля формы содержит несколько входов, которые должны быть семантически сгруппированы в <fieldset> с <legend> для улучшения доступности. Пример использования в шаблоне:

{% if field.use_fieldset %}
  <fieldset>
  {% if field.label %}{{ field.legend_tag }}{% endif %}
{% else %}
  {% if field.label %}{{ field.label_tag }}{% endif %}
{% endif %}
{{ field }}
{% if field.use_fieldset %}</fieldset>{% endif %}

{{ field.value }}

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

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