Формы в Django

Использование полей в формах Django

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

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

BooleanField(): Данное поле предназначено для ввода логического(True или False) значения. Создаёт следующий HTML-код:

<input type="checkbox">

Возвращает значение True - если флажок отмечен и False - если флажок не отмечен.

NullBooleanField(): Данное поле предназначено для ввода логического(Null, True или False) значения. Создаёт следующий HTML-код:

<select>
<option value="1" selected="selected">Unknown</option>
<option value="2">Yes</option>
<option value="3">No</option>
</select>

CharField(): Данное поле предназначено для ввода текста. Создаёт следующий HTML-код:

<input type="text">

Параметры поля:

max_length: максимальная длина вводимого текста

min_length: минимальная длина вводимого текста

strip: при значении True (по умолчанию) начальные и конечные пробелы удаляются

empty_value: значение, применяемое для представления пустого поля

EmailField(): Данное поле предназначено для ввода адреса электронной почты. Создаёт следующий HTML-код:

<input type="email">

Параметры поля, что и у CharField.

GenericIPAddressField(): Данное поле предназначено для ввода IP-адреса в формате IP4v или IP6v. Создаёт следующий HTML-код:

<input type="text">

RegexField(regex="регулярное выражение"): Данное поле предназначено для ввода текста, который должен соответствовать определенному регулярному выражению. Создаёт следующий HTML-код:

<input type="text">

SlugField(): Данное поле предназначено для ввода текста, который условно называется slug, то есть последовательность символов в нижнем регистре, чисел, дефисов и знаков подчеркивания. Создаёт следующий HTML-код:

<input type="text">

URLField(): Данное поле предназначено для ввода ссылок. Создаёт следующий HTML-код:

<input type="url">

UUIDField(): Данное поле предназначено для ввода UUID (универсального уникального идентификатора). Создаёт следующий HTML-код:

<input type="text">

ComboField(fields=[field1, field2, ..]): Данное поле предназначено для ввода текста, полностью аналогично обычному текстовому полю за исключением, что требует, чтобы вводимый текст соответствовал требованиям тех полей, которые передаются через параметр fields. Создаёт следующий HTML-код:

<input type="text">

MultiValueField(fields=[field1, field2, ..]): Данное поле предназначено для создания сложных компоновок, состоящих из нескольких полей.

FilePathField(path="каталог файлов"): Данное поле предназначено для создания списка(select), который содержит все папки и файлы в определенном каталоге. Создаёт следующий HTML-код:

<select>
  <option value="file1">folder/file1</option>
  <option value="file2">folder/file2</option>
  <option value="file3">folder/file3</option>
  //.............................................
</select>

Параметры поля:

path: абсолютный путь к каталогу

recursive: если равно False (значение по умолчанию), то элемент отображает файлы только непосредственно из этой папки. Если равно True, то также отображается содержимое вложенных папок

match: регулярное выражение, которому должны соответствовать файлы для отображения

allow_files: представляет значение True (значение по умолчанию) или False. Указывает, должны ли быть включены файлы по определенному пути

allow_folders: представляет значение True (значение по умолчанию) или False. Указывает, должны ли быть включены папки по определенному пути

FileField(): Данное поле предназначено для выбора файла. Создаёт следующий HTML-код:

<input type="file">

ImageField(): Данное поле предназначено для выбора файла изображения. Создаёт следующий HTML-код:

<input type="file">

DateField(): Данное поле предназначено для установки даты. В создаваемое поле вводится текст, который может быть сконвертирован в дату, например, 2019-10-15 или 11/27/19. Создаёт следующий HTML-код:

<input type="text">

TimeField(): Данное поле предназначено для ввода времени, например, 12:10:50 или 12:10. Создаёт следующий HTML-код:

<input type="text">

DateTimeField(): Данное поле предназначено для ввода даты и времени, например, 2019-10-15 12:10:50 или 11/27/19 12:10. Создаёт следующий HTML-код:

<input type="text">

DurationField(): Данное поле предназначено для ввода временного промежутка. Вводимый текст должен соответствовать формату DD HH:MM:SS, например, 3 1:20:30 (3 дня 1 час 20 минут 30 секунд). Создаёт следующий HTML-код:

<input type="text">

SplitDateTimeField(): Данное поле предназначено для раздельного ввода даты и времени. Создаёт следующий HTML-код:

<input type="date" name="0">
<input type="time" name="1">

IntegerField(): Данное поле предназначено для ввода целочисленных значений. Создаёт следующий HTML-код:

<input type="number">

Параметры поля:

max_value: максимально возможное значение

min_value: минимально возможное значение

step_size: шаг приращения числа

DecimalField(): Данное поле предназначено для ввода значений с фиксированной точностью(Decimal). Создаёт следующий HTML-код:

<input type="number">

Параметры поля:

max_value: максимально возможное значение

min_value: минимально возможное значение

max_digits: максимальное количество цифр в числе

decimal_places: максимальное количество знаков после запятой

step_size: шаг приращения числа

FloatField(): Данное поле предназначено для ввода значений с плавающей точкой. Создаёт следующий HTML-код:

<input type="number">

Параметры поля:

max_value: максимально возможное значение

min_value: минимально возможное значение

step_size: шаг приращения числа

ChoiceField(choices=кортеж_кортежей): Данное поле предназначено для создания списка(select), каждый из его элементов формируется на основе отдельного кортежа. Например:

colors = forms.ChoiceField(choices=((1, "White"), (2, "Blue"), (3, "Red")))

Создаст следующий HTML-код:

<select name="colors" id="id_colors">
    <option value="1">White</option>
    <option value="2">Blue</option>
    <option value="3">Red</option>
</select>

TypedChoiceField(choices=кортеж_кортежей, coerce=функция_преобразования, empty_value=None): Данное поле предназначено для создания списка(select) на основе кортежа. Однако дополнительно принимает функцию преобразования, которая преобразует каждый элемент. И также принимает параметр empty_value, который указывает на значение по умолчанию.

MultipleChoiceField(choices=кортеж_кортежей): Данное поле предназначено для создания списка(select) на основе кортежа, как и forms.ChoiceField, добавляя к создаваемому полю атрибут multiple="multiple". То есть список поддерживает множественный выбор.

TypedMultipleChoiceField(choices=кортеж_кортежей, coerce=функция_преобразования, empty_value=None): аналог TypedChoiceField() для списка с множественным выбором.

JSONField(): Данное поле предназначено для приёма данных в формате JSON. Виджет по умолчанию Textarea.

Параметры поля:

encoder: класс производный от json.JSONEncoder для сериализации данных в формат JSON. Значение по умолчанию - json.JSONEncoder.

decoder: класс производный от json.JSONDecoder для десериализации данных из формата JSON. Значение по умолчанию - json.JSONDecoder.

Виджеты Django

Каждое поле, когда оно выводится на НТМL-страницу, имеет типичный для него внешний вид. Например, поле для ввода текста имеет обрамление в виде рамки. За внешний вид полей отвечает виджет - представление элемента ввода на НТМL странице. Виджеты не следует путать с полями формы. Поля формы имеют дело с логикой проверки ввода и используются непосредственно в шаблонах. Виджеты же имеют дело с отображением элементов ввода НТМL-формы на веб-странице и извлечением необработанных отправленных данных. Однако виджеты должны быть назначены полям формы.

Всякий раз, когда вы указываете поле в форме, Django задействует виджет по умолчанию, соответствующий тому типу данных, которые должны отображаться. Ранее рассмотренные поля при генерации разметки использовали определенные
виджеты из пакета forms.widgets.

Например, класс CharField - виджет forms.widgets.Textinput, а класс ChoiceField - виджет forms.widgets.Select.

Однако есть ряд виджетов, которые по умолчанию не используются полями форм, но тем не менее мы можем их применять:

PasswordInput: генерирует поле для ввода пароля <input type="password">

HiddenInput: генерирует скрытое поле <input type="hidden">

MultipleHiddenInput: генерирует набор скрытых полей

Textarea: генерирует многострочное текстовое поле <textarea></textarea>

RadioSelect: генерирует список переключателей (радиокнопок) <input type="radio">

CheckboxSelectMultiple: генерирует список флажков <input type="checkbox">

TimeInput: генерирует поле для ввода времени (например, 12:41 или 12:41:32)

SelectDateWidget: генерирует три поля select для выбора дня, месяца и года

SplitHiddenDateTimeWidget: использует скрытое поле для хранения даты и времени

FileInput: генерирует поле для выбора файла

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

Каждый экземпляр класса Field имеет метод clean(), который принимает единственный аргумент и вызывает исключение django.forms.ValidationError в случае ошибки или возвращает чистое значение:

Field.clean(value)

Вот пример использования этого метода:

from django import forms
f = forms.EmailField()
f.clean('info@example.com')
f.clean('Ошибка в написании email адреса')

Некоторые классы Field принимают дополнительные аргументы. Приведенные далее аргументы принимаются всеми полями:

required - указывает на необходимость обязательного заполнения поля (по умолчанию: required=True). Для того чтобы сделать поле необязательным для заполнения, нужно указать: required=False;

label - позволяет определить видимую пользователем метку для поля (например, если имя поля name и на экране нужно показать Ваше имя, то это можно сделать следующим образом: name = forms.CharField(label='ваше имя')

label_suffix - позволяет переопределить атрибут формы label_suffix для каждого поля. Например:

class ContactForm(forms.Form):
    age = forms.IntegerField()
    nationality = forms.CharField()
    captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' = ')

initial - позволяет определять начальное значение для поля при его отображении на незаполненной форме. Например:
```
from django import forms

class CommentForm(forms.Form):
    name = forms.CharField(initial='Ваше имя')
    url = forms.URLField(initial='http://')
    comment = forms.CharField()
```

widget - позволяет указать класс Widget, который следует использовать при отображении поля вместо того, который задан по умолчанию;

help_text - позволяет указать описание данных, которые нужно внести в поле. Если вы укажете help_text, он будет показан около поля при отображении формы с помощью вспомогательных методов. Например:
```
from django import forms

class HelpTextContactForm(forms.Form):
    subject = forms.CharField(max_length=100, help_text='He более 100 символов')
    message = forms.CharField()
    sender = forms.EmailField(help_text='email адрес')
    cc_myself = forms.BooleanField(required=False)
```
Здесь представлен пример формы, в которой help_text определен у двух полей.

error_messages - позволяет изменить стандартные сообщения об ошибках, которые выдает поле. Создайте словарь с ключами тех сообщений, которые вы желаете изменить. Если не задать значение этому аргументу:
```
from django import forms

generic = forms.CharField()
generic.clean('')
```
то будет выдано стандартное сообщение об ошибке: This field is required. Если этот аргумент задать явно, например:
```
name = forms.CharField(error_messages={'required':'Ошибка, не введено имя'})
name.clean('')
```
то будет выдано заданное сообщение об ошибке: Ошибка, не введено имя;

validators - позволяет указать список функций, осуществляющих проверку поля;

localize - включает локализацию для данных формы как на входе, так и на выходе;

disabled - этот аргумент принимает булево значение. При значении True - выключает поля формы, используя НТМL-атрибут disabled. Даже если пользователь отправит данные этого поля, они будут проигнорированы и использовано значение из начальных данных, которые были переданы в форму.

В следующем шаге мы рассмотрим некоторые из них подробнее.