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

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

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

Джанго Formкласс ¶

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

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

Поля формы сами по себе являются классами; они управляют данными формы и выполняют проверку при отправке формы. A DateFieldи a 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запрос, который отправляется на сервер, будет содержать данные формы.

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

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

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

На этом этапе намного проще заставить 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 = ['[email protected]']
    if cc_myself:
        recipients.append(sender)

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

Параметры отрисовки формы ¶

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

Дополнительные сведения см. В разделе « Вывод форм в формате HTML» .

Отрисовка полей вручную ¶

Нам не нужно позволять Django распаковывать поля формы; мы можем сделать это вручную, если захотим (например, позволив нам изменить порядок полей). Каждое поле доступно как атрибут используемой формы , а в шаблоне Django будет отображаться соответствующим образом. Например:{{ form.name_of_field }}

{{ 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.label }}

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

{{ field.label_tag }}

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

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

{{ field.id_for_label }}

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

{{ field.value }}

Значение поля. напр [email protected].

{{ field.html_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 }}

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

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