Использование форм ¶

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 можно легко добавить в закладки, поделиться или повторно отправить.

Класс Form Django ¶

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

Так же, как поля класса шаблона соответствуют полям базы данных, поля класса формы соответствуют элементам <input> HTML-формы (один ModelForm соответствует полям класса шаблона к элементам <input> HTML-формы через форму 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 ¶

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

См. Раздел Отображение форм в HTML для получения дополнительной информации об этом.

Ручное отображение полей ¶

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

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

Например, метка поля .Adresse de courriel

{{ field.label_tag }}

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

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

{{ field.id_for_label }}

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

{{ field.value }}

Например, значение поля [email protected] .

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

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

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