Документация Django 1.9
Этот документ знакомит с деталями API форм Django. Сначала вы должны прочитать введение в использование форм.
Заполненные и незаполненные формы¶
Экземпляр класса Form может быть заполнен набором данных или не заполнен.
Если он заполнен, то у него есть возможность валидации полученных данных и генерации заполненной формы в виде HTML кода.
Если он не заполнен, то выполнить валидацию невозможно (так как нет для этого данных!), но есть возможность сгенерировать HTML код пустой формы.
Для привязки данных к форме, передайте данные в виде словаря в качестве первого параметра конструктора класса Form :
Если вам требуется определять заполненность экземпляров форм во время работы программы, обратитесь к значению атрибута формы is_bound :
Следует отметить, что передача форме пустого словаря создаёт заполненную форму без данных:
Использование форм для проверки данных¶
Главной задачей объекта Form является проверка данных. У заполненного экземпляра Form вызовите метод is_valid() для выполнения проверки и получения её результата:
Начнём с неправильных данных. В этом случае поле subject будет пустым (ошибка, так как по умолчанию все поля должны быть заполнены), а поле sender содержит неправильный адрес электронной почты:
Обратитесь к атрибуту errors для получения словаря с сообщениями об ошибках:
В этом словаре, ключами являются имена полей, а значениями – списки юникодных строк, представляющих сообщения об ошибках. Сообщения хранятся в виде списков, так как поле может иметь множество таких сообщений.
Form.errors. as_json (escape_html=False)¶
Возвращает ошибки в JSON формате.
Если вы не хотите использовать экранирование на стороне клиента, можете передать аргумент escape_html=True и все ошибки будет экранированы, теперь их можно вставлять непосредственно в HTML.
Form. has_error (field, code=None)¶
Поведение незаполненных форм¶
Бессмысленно проводить проверку незаполненной формы, но покажем, что происходит с такой формой:
Динамические начальные значения¶
Используйте атрибут initial для определения начальных значений полей формы во время работы приложения. Например, вам может потребоваться заполнить поле username именем текущего пользователя.
Эти значения только отображаются на незаполненных формах, они не будут доступны пока форма не будет отправлена пользователем.
Проверяем какие данные формы были изменены¶
После отправки формы, мы создаем ее, предоставляя изначальные данные, и теперь может проверить изменились ли они:
Обращение к полям из формы¶
Вы можете изменить поле:
Будьте осторожны, не изменяйте атрибут base_fields т.к. эти изменения повлияют на все экземпляры ContactForm в текущем процессе Python:
Доступ к “чистым” данным¶
Каждое поле в классе Form отвечает не только за проверку, но и за нормализацию данных. Это приятная особенность, так как она позволяет вводить данные в определённые поля различными способами, всегда получая правильный результат.
Если данные не прошли проверку, то атрибут cleaned_data будет содержать только значения тех полей, что прошли проверку:
Вы можете написать код для выполнения проверки определённых полей формы (используя их имена) или для проверки всей формы (рассматривая её как комбинацию полей). Подробная информация изложена в Проверка форм и полей формы.
Выдача формы в виде HTML¶
Второй задачей объекта Form является представление себя в виде HTML кода. Для этого объект надо просто “распечатать”:
По умолчанию в HTML форма представляется в виде таблицы, т.е. каждое поле обёрнуто в
Метод as_p() представляет форму в виде последовательности тегов
, по одному на каждое поле:
as_ul() ¶
as_table() ¶
Наконец, метод as_table() выводит форму в виде таблицы. Этот метод используется по умолчанию:
Стилизация обязательных полей или полей с ошибкой¶
Стилизация полей формы, обязательных для заполнения или имеющих ошибку, является общей практикой. Например, вы можете выделять обязательные поля жирным шрифтом, а поля с ошибкой выводить на красном.
Класс Form имеет ряд возможностей, которые вы можете использовать для добавления атрибутов class к обязательным полям и полям с ошибками: просто определите атрибут Form.error_css_class и/или Form.required_css_class attributes:
Настройка тегов и атрибута id ¶
По умолчанию методы для рендеринга форма включают:
HTML атрибуты id элементов формы.
Атрибуты id создаются с помощью добавления префикса id_ к именам полей формы. Это поведение является изменяемым, таким образом вы можете изменить его или вообще удалить эти атрибуты и тег из формы.
Строка(по умолчанию двоеточие ( : )), которая будет добавлена к названию метки поля. Строка локализирована и можно перевести на разные языки.
Есть возможность заменить это двоеточие на другой символ или вообще убрать его. Для этого надо воспользоваться параметром label_suffix :
Порядок полей¶
Есть и другие способы переопределить порядок полей в форме:
Form. order_fields (field_order)¶
Отображение ошибок¶
Настройка формата списка ошибок¶
Точное управление выводом¶
Метод __str__() ( __unicode__ в Python 2) этого объекта возвращают HTML для данного поля.
Для получение одного BoundField используйте синтаксис поиска в словаре, применяя имя поля в качестве ключа:
Вывод указанного поля соответствует настройке auto_id :
Атрибуты BoundField ¶
Название, которое будет использоваться в HTML атрибуте name виджета. Учитывает prefix формы.
Этот атрибут рендерит ID поля. Например, вы можете использовать его, если вы самостоятельно создаете для поля (несмотря на то, что label_tag() делает это для вас):
По умолчанию, он равен названию поля с префиксом id_ (“ id_my_field ” для примера выше). Вы можете изменить ID, передав его в параметре attrs виджета. Например, определив поле следующим образом:
и используя пример выше, получите следующий результат:
Название текущего поля в форме:
Методы BoundField ¶
Этот метод в основном используется внутренним кодом. Вам следует использовать виджет вместо него.
BoundField. as_widget (widget=None, attrs=None, only_initial=False)¶
only_initial используется Django и не должен указываться явно.
Когда вы применяете общие методы для отображения формы, для выделения обязательных полей формы или полей, которые содержат ошибки, используются CSS классы. Если вы вручную выводите форму, вы можете получить доступ к этим классам через метод css_classes :
Если потребуется предоставить дополнительные классы для ошибок и обязательных полей, вы можете указать эти классы в качестве аргумента:
Чтобы отдельно отрендерить label поля, вызовите метод label_tag() :
Используйте этот метод для выдачи “сырого” значения данного поля, как будто бы оно было отображено через Widget :
Настройка BoundField ¶
В собственном поле формы можно переопределить метод get_bound_field() :
Field. get_bound_field (form, field_name)¶
Привязка загруженных файлов к форме¶
Работа с формами, которые содержат поля FileField и ImageField немного отличается от работы с обычными формами.
Сначала, для того, чтобы загружать файлы, вам потребуется назначить форме атрибут enctype :
Наследование форм¶
Если у вас есть несколько классов Form с одинаковыми полями, вы можете воспользоваться наследованием форм, чтобы убрать дублирование кода.
Также можно наследовать несколько форм, рассматривая формы как “смесь”(mixin). В этом примере форма BeatleForm наследует формы PersonForm и InstrumentForm (именно в этом порядке) и её список полей включает в себя поля из родительских классов:
Префиксы для форм¶
Вы можете размещать несколько форм в одном теге
Введите слова для поиска или имя модуля, класса или функции.
Проверка форм и полей ¶
Проверка формы происходит при очистке данных. Если вы хотите настроить этот процесс, есть несколько точек входа, где можно внести изменения, каждая из которых преследует разные цели. При обработке формы используются три метода очистки. Обычно они выполняются при is_valid() вызове метода формы. Существуют и другие операции, которые также могут вызывать очистку и проверку (доступ к атрибуту errors или прямой вызов full_clean() ), но в принципе это не является частью обычного процесса.
Проверка формы разделена на несколько шагов, которые можно персонализировать или перегружать:
Метод validate() поля Field заботится о конкретной проверке поля, что не подходит для валидатора. Он принимает значение, которое уже было преобразовано в правильный тип, и генерирует исключение в ValidationError случае возникновения ошибки. Этот метод ничего не возвращает и не должен изменять значение. Его можно перегружать для обработки логики проверки, которую вы не можете или не хотите добавлять в валидатор.
Поскольку методы проверки поля выполнялись во время clean() вызова, у вас также есть доступ к атрибуту errors формы, который содержит все ошибки, сгенерированные во время очистки отдельного поля.
Также обратите внимание на то, что при переопределении clean() метода подкласса необходимо учитывать особые моменты ( дополнительную информацию ModelForm см. В документации ModelForm ).
Примеры для каждого из этих методов показаны ниже.
Генерация ValidationError ¶
Для большей гибкости сообщений об ошибках и облегчения их переопределения вот несколько рекомендаций:
Предоставьте конструктору code описательную ошибку:
Не объединяйте переменные в сообщениях; используйте заполнители, а также параметр params конструктора:
Предпочитайте подстановку словарного ключа позиционному форматированию. Это позволяет размещать переменные в любом порядке или даже полностью их опускать при перезаписи сообщения:
Включите сообщение в вызов, gettext чтобы активировать его перевод:
Следование этим рекомендациям особенно полезно при написании многоразовых форм, полей форм или полей шаблонов.
Методы Form.errors.as_data() и Form.errors.as_json() значительно выигрывают от ValidationError полностью заполненных объектов (с именем code и словарем params ).
Генерация нескольких ошибок ¶
Использование валидации на практике ¶
В предыдущих разделах объяснялось, как в целом работает проверка форм. Поскольку иногда легче расставить вещи по своим местам, изучив код в контексте, вот серия небольших примеров, в которых используется каждая из функций, описанных выше.
Использование валидаторов ¶
Валидаторы могут использоваться для проверки значений поля; Например, давайте посмотрим на поле SlugField Django:
Очистка полей формы по умолчанию ¶
Во-первых, давайте создадим настраиваемое поле формы, которое проверяет, что его входное значение представляет собой строку, содержащую адреса электронной почты, разделенные запятыми. Полный класс выглядит так:
Для каждой формы, использующей это поле, эти методы будут выполняться до того, как что-либо будет сделано с данными в поле. Это очистка, специфичная для этого типа поля, независимо от того, как оно будет использоваться позже.
Давайте создадим форму, ContactForm чтобы показать, как можно использовать это поле:
Очистка определенного атрибута поля ¶
Очистка и проверка полей, которые зависят друг от друга ¶
К моменту clean() вызова метода формы все методы очистки для каждого поля уже будут выполнены (см. Два предыдущих раздела), так что self.cleaned_data они будут заполнены любыми данными, прошедшими проверку до этого момента. Поэтому вы также должны помнить о том, что поля, которые вы хотите проверить, возможно, не прошли предварительный этап проверки на уровне отдельного поля.
Второй подход к сообщению об ошибках проверки может включать назначение сообщения об ошибке одному из полей. В этом случае давайте назначим сообщение об ошибке для строк «subject» и «cc_myself» в представлении формы. Будьте осторожны, если будете делать это на практике, так как это может привести к путанице в представлении формы. Здесь мы показываем, что возможно, но оставляем вам самому решать, что можно сделать в вашем конкретном контексте. Наш новый код (заменяющий предыдущий пример) выглядит так:
Django — обработка ошибок в ajax-формах
Все мы знаем что Django — очень мощный и динамично развивающийся фреймворк для создания веб-приложений. Однако, несмотря на наступление эпохи Веб 2.0, в нём всё ещё нет встроенных механизмов для работы с AJAX, в частности отправки и проверки форм. Возможно django просто не хочет навязывать пользователю какой-то js-фреймворк и хочет оставаться гибкой в этом вопросе, но так или иначе при разработке часто требуются формы, работающие через ajax, без перезагрузок страниц.
О создании таких форм и работе с ними и пойдёт речь в данной статье.
Сразу оговорюсь, что идея не нова, и существует несколько библиотек, реализующих требуемую функциональность, например одна из них — http://www.dajaxproject.com/.
Для тех же, кто предпочитает сам управлять взаимодействием клиента с сервером или тех, кто не хочет втягивать в проект дополнительную библиотеку и иметь дело с её багами, я расскажу как изобрести велосипед реализовать механизм самостоятельно и опишу различные способы решения проблемы.
Форма
Для примера возьмём простую форму регистрации пользователя на сайте:
В реальной жизни вы, скорее всего, будете наследовать эту форму от модели данных, но для нашего примера это несущественно.
Вывод формы
Обработка формы
Финальная версия view:
Финальная версия view:
Обработка на стороне клиента, javascript:
Стоит также заметить, что при использовании второго способа и описанного ранее шаблона формы, ошибки будут отображаться с использованием элемента списка , для другого отображения необходимо сделать другой шаблон либо переопределить класс ошибок для формы.
Вот и всё. Прилагаю скриншоты получившейся формы в различных состояниях:
Буду рад услышать комментарии и узнать другие способы работы с ajax-формами.
Документация Django 3.0
Проверка формы происходит при нормализации её данных. При возникновении необходимости вмешаться в этот процесс, есть много мест, где можно это сделать и которые влияют на разные этапы проверки. Во время обработки формы вызываются три типа методов для нормализации данных. Процесс проверки запускается при вызове метода is_valid() формы. Существуют ситуации, которые запускают нормализацию и проверку данных (обращение к свойству errors или прямой вызов метода full_clean() ), но они возникают достаточно редко.
Проверка формы состоит из нескольких этапов, каждый из которых может быть настроен или переопределён:
Метод validate() поля выполняет специфическую для поля проверку данных и приводит значение к правильному типу данных, или вызывает исключение ValidationError на любую ошибку. Этот метод не возвращает значение и не должен изменять проверяемые данные. Если вам надо обеспечить логику, которую невозможно или нежелательно выносить в валидатор, то вам следует переопределить этот метод.
For example, if you wanted to validate that the contents of a CharField called serialnumber was unique, clean_serialnumber() would be the right place to do this. You don’t need a specific field (it’s a CharField ), but you want a formfield-specific piece of validation and, possibly, cleaning/normalizing the data.
Метод clean() потомка формы может выполнять любую проверку, которая нуждается в одновременном доступе к данным нескольких полей. Именно здесь вы можете проверять, что если поле A заполнено, то поле B должно содержать правильный адрес электронной почты и так далее. Данные, которые возвращает этот метод, помещаются в свойство cleaned_data формы.
Примеры для каждого из этих методов показаны ниже.
Вызов ValidationError ¶
Для удобной работы с ошибками валидации используйте следующие правила:
Передайте при создании код ошибки через аргумент code :
Используйте именованные параметры в сообщении. Это позволит использовать переменные в любом параметре при переопределении сообщения:
Оберните сообщения в gettext для последующего перевода:
Соблюдать правила очень важно при создании переносимых форм, полей форм и моделей.
Не рекомендуется, но если вы в конце цепочки валидации(например, метод clean() формы) и никогда не будете переопределять сообщение, можно просто сделать:
Методы Form.errors.as_data() и Form.errors.as_json() используют все возможности ValidationError (включая code и params ).
Вызов нескольких ошибок¶
При обнаружении нескольких ошибок в процессе нормализации поля и при наличии желания отобразить их одновременно на форме, следует передать их в виде списка в конструктор исключения.
Использование проверки на практике¶
Выше мы рассмотрели как осуществляется проверка форм в целом. Так как временами бывает проще разобраться с функционалом, просмотрев его в действии, далее показан ряд небольших примеров, которые используют описанные возможности.
Использование валидаторов¶
Django’s form (and model) fields support use of utility functions and classes known as validators. A validator is a callable object or function that takes a value and returns nothing if the value is valid or raises a ValidationError if not. These can be passed to a field’s constructor, via the field’s validators argument, or defined on the Field class itself with the default_validators attribute.
Validators can be used to validate values inside the field, let’s have a look at Django’s SlugField :
As you can see, SlugField is a CharField with a customized validator that validates that submitted text obeys to some character rules. This can also be done on field definition so:
Встроенная проверка поля формы¶
Давайте сначала создадим собственное поле формы, которое проверяет, что переданные ему данные — это строка, содержащая адреса электронной почты, разделенные запятыми. Класс такого поля будет выглядеть следующим образом:
Каждая форма, использующая такое поле, будет вызывать эти методы до выполнения всех остальных действий с данными поля. Такая проверка привязана к этому типу поля и не зависит от дальнейшего его использования.
Let’s create a ContactForm to demonstrate how you’d use this field:
Use MultiEmailField like any other form field. When the is_valid() method is called on the form, the MultiEmailField.clean() method will be run as part of the cleaning process and it will, in turn, call the custom to_python() and validate() methods.
Проверка атрибута определённого поля¶
Очистка и проверка полей, которые зависят друг от друга¶
К моменту вызова метода формы clean() все clean() методы полей уже отработали. Таким образом, свойство формы self.cleaned_data будет заполнено данными, прошедшими проверку. Следовательно, надо принять во внимание возможность того, что данные некоторых полей не прошли начальную поверку.
В данном коде, при возникновении ошибки во время проверки данных, форма отобразит сообщение об ошибке сверху (обычное поведение), описывая проблему.
Вызов super().clean() обеспечивает проверку данных в родительском классе. Если ваша форма наследуется от класса, который не возвращает словарь cleaned_data из метода clean() (это не обязательно), не записывайте в cleaned_data результат вызова super() и используйте вместо этого self.cleaned_data :
Второй способ подразумевает назначение ошибки одному из полей. В нашем случае, давайте назначим сообщение об ошибке обоим полям («subject» и «cc_myself») при отображении формы. Использовать этот способ надо аккуратно, так как он может запутать пользователя. Мы лишь показываем возможные варианты, оставляя решение конкретной задачи вам и вашим дизайнерам. Наш новый код (заменяющий предыдущий пример) выглядит так:
Работа с формами¶
Если вы не планируете создавать веб-сайты и приложения, которые будут только публиковать содержимое и не будут принимать данные от посетителей, вам необходимо понимать и использовать формы.
Django предоставляет ряд инструментов и библиотек, которые помогут вам создать формы, принимающие ввод от посетителей сайта, а затем обрабатывающие и отвечающие на него.
HTML-формы¶
В качестве примера, форма входа для администратора Django содержит несколько элементов : один из type=»text» для имени пользователя, один из type=»password» для пароля и один из type=»submit» для кнопки «Войти». Он также содержит некоторые скрытые текстовые поля, которые пользователь не видит, и которые Django использует для определения того, что делать дальше.
Он также сообщает браузеру, что данные формы должны быть отправлены на URL, указанный в атрибуте
Вам понадобится представление, которое отображает шаблон, содержащий HTML-форму, и которое может предоставлять поле current_name по мере необходимости.
Это очень простая форма. На практике форма может содержать десятки или сотни полей, многие из которых должны быть предварительно заполнены, и мы можем ожидать, что пользователь пройдет цикл редактирования-отправки несколько раз, прежде чем завершит операцию.
Мы можем потребовать некоторой проверки в браузере, даже до отправки формы; мы можем захотеть использовать гораздо более сложные поля, которые позволят пользователю делать такие вещи, как выбор даты из календаря и так далее.
На данном этапе гораздо проще заставить Django сделать большую часть этой работы за нас.