Наборы форм Formsets

Класс BaseFormSet¶
Набор форм – это уровень абстракции для работы с несколькими формами на одной странице. Это может быть лучше по сравнению с сеткой данных. Допустим, у вас есть следующая форма:

Вы можете разрешить пользователю создавать несколько статей одновременно. Чтобы создать набор форм из ArticleForm, вы должны сделать:

Теперь вы создали класс formset с именем ArticleFormSet. Создание набора форм дает вам возможность перебирать формы в наборе форм и отображать их так же, как в обычной форме:

И вы можете увидеть только одну пустую форму. Количество отображаемых пустых форм определяется дополнительным параметром. По умолчанию formset_factory () определяет одну дополнительную форму; В следующем примере будет создан класс formset для отображения двух пустых форм:

Итерирование по набору форм будет отображать формы в порядке их создания. Вы можете изменить этот порядок, предоставив альтернативную реализацию для метода __iter __ ().

Однако в этом случае, для правильной работы Formsets, если вы переопределите __iter__, вам также потребуется переопределить __getitem__, чтобы иметь корректное поведение.

Использование исходных данных с набором форм

Исходные данные – это то, что определяет основное удобство использования набора форм. Как показано выше, вы можете определить количество дополнительных форм. Это означает, что вы сообщаете набору форм, сколько дополнительных форм нужно показать в дополнение к количеству форм, которые он генерирует из исходных данных. Давайте посмотрим на пример:

В настоящее время есть три формы, показанные выше. Один для исходных данных, которые были переданы и две дополнительные формы. Также обратите внимание, что мы передаем список словарей в качестве исходных данных.

Если вы используете инициал для отображения набора форм, вы должны передать тот же инициал при обработке отправки этого набора, чтобы набор мог определить, какие формы были изменены пользователем. Например, у вас может быть что-то вроде: ArticleFormSet (request.POST, initial = […]).

Ограничение максимального количества форм

Параметр max_num для formset_factory () дает вам возможность ограничить количество форм, которые будет отображать formset.

Если значение max_num больше, чем количество существующих элементов в исходных данных, в набор форм будет добавлено до дополнительных дополнительных пустых форм, если общее число форм не превышает max_num. Например, если extra = 2 и max_num = 2 и набор форм инициализируется одним начальным элементом, будет отображаться форма для исходного элемента и одна пустая форма.

Если количество элементов в исходных данных превышает max_num, все исходные формы данных будут отображаться независимо от значения max_num, и дополнительные формы не будут отображаться. Например, если extra = 3 и max_num = 1 и набор форм инициализируется с двумя исходными элементами, будут отображены две формы с исходными данными.

Значение max_num None (по умолчанию) накладывает верхний предел на количество отображаемых форм (1000). На практике это эквивалентно безграничному.

По умолчанию max_num влияет только на количество отображаемых форм и не влияет на проверку. Если validate_max = True передается в formset_factory (), то max_num повлияет на валидацию.

Проверка набора форм

Проверка с помощью набора форм практически идентична обычной форме. В наборе форм есть метод is_valid, обеспечивающий удобный способ проверки всех форм в наборе форм:

Мы не передали никаких данных в форму, что привело к правильной форме. Набор форм достаточно умен, чтобы игнорировать дополнительные формы, которые не были изменены. Если мы предоставим недействительную статью:

Как мы видим, formset.errors – это список, записи которого соответствуют формам в formset. Проверка была выполнена для каждой из двух форм, и ожидаемое сообщение об ошибке появляется для второго элемента.

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

BaseFormSet.total_error_count () ¶
Чтобы проверить, сколько ошибок в наборе форм, мы можем использовать метод total_error_count:

Мы также можем проверить, отличаются ли данные формы от исходных данных (то есть форма была отправлена без каких-либо данных):

Понимание ManagementForm

Возможно, вы заметили дополнительные данные (form-TOTAL_FORMS, form-INITIAL_FORMS и form-MAX_NUM_FORMS), которые были необходимы в данных набора форм выше. Эти данные необходимы для ManagementForm. Эта форма используется набором форм для управления коллекцией форм, содержащихся в наборе форм. Если вы не предоставите эти данные управления, возникнет исключение:

Он используется для отслеживания количества отображаемых экземпляров форм. Если вы добавляете новые формы с помощью JavaScript, вам также следует увеличить количество полей в этой форме. С другой стороны, если вы используете JavaScript, чтобы разрешить удаление существующих объектов, то вам нужно убедиться, что удаляемые объекты правильно помечены для удаления, включив форму – # – DELETE в данные POST. Ожидается, что все формы присутствуют в данных POST независимо.

Форма управления доступна в качестве атрибута самого набора форм. При рендеринге набора форм в шаблоне вы можете включить все данные управления, выполнив {{my_formset.management_form}} (при необходимости подставляя имя вашего набора форм).

total_form_count и initial_form_count

BaseFormSet имеет несколько методов, которые тесно связаны с ManagementForm, total_form_count и initial_form_count.

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

empty_form¶
BaseFormSet предоставляет дополнительный атрибут empty_form, который возвращает экземпляр формы с префиксом __prefix__ для более легкого использования в динамических формах с JavaScript.

Проверка пользовательского набора форм¶

Formset имеет метод clean, похожий на метод класса Form. Здесь вы определяете свою собственную проверку, которая работает на уровне набора форм:

Метод clean для formset вызывается после того, как были вызваны все методы Form.clean. Ошибки будут доступны с помощью метода non_form_errors () в наборе форм.

Проверка количества форм в наборе форм

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

validate_max¶
Если validate_max = True передается в formset_factory (), проверка также проверит, что число форм в наборе данных, за исключением тех, которые помечены для удаления, меньше или равно max_num.

validate_max = True приводит к тому, что будет проверено строго max_num форм, даже если количество форм превысило max_num, потому что объем исходных данных был чрезмерным.

Независимо от validate_max, если число форм в наборе данных превышает max_num более чем на 1000, то форма не сможет проверить, как если бы был установлен validate_max, и дополнительно будет проверяться только первая 1000 форм выше max_num. Остальная часть будет усечена полностью. Это необходимо для защиты от атак с истощением памяти с использованием поддельных POST-запросов.

validate_min
Если validate_min = True передается в formset_factory (), проверка также проверит, что число форм в наборе данных, за исключением помеченных для удаления, больше или равно min_num.

Работа с порядком и удалением форм

Formset_factory () предоставляет два необязательных параметра can_order и can_delete, которые помогают упорядочивать формы в наборах форм и удалять формы из набора форм.

can_order¶
BaseFormSet.can_order¶
По умолчанию: False

Позволяет создать форму с возможностью указание порядка:

Это добавляет дополнительное поле к каждой форме. Это новое поле называется ORDER и представляет собой forms.IntegerField. Для форм из исходных данных им автоматически присваивается числовое значение. Давайте посмотрим, что произойдет, когда пользователь изменит эти значения:

BaseFormSet также предоставляет атрибут ordering_widget и метод get_ordering_widget (), которые управляют виджетом, используемым с can_order.

BaseFormSet.ordering_widget¶
По умолчанию: NumberInput

Установите ordering_widget, чтобы указать класс виджета, который будет использоваться с can_order:

get_ordering_widget¶
BaseFormSet.get_ordering_widget () ¶
Переопределите get_ordering_widget (), если вам нужно предоставить экземпляр виджета для использования с can_order:

can_delete¶
BaseFormSet.can_delete¶
По умолчанию: False

Позволяет создать набор форм с возможностью выбора форм для удаления:

Подобно can_order это добавляет новое поле к каждой форме с именем DELETE и представляет собой forms.BooleanField. Когда данные проходят через пометку любого из полей удаления, вы можете получить к ним доступ с помощью delete_forms:

Если вы используете ModelFormSet, экземпляры модели для удаленных форм будут удалены при вызове formset.save ().

Если вы вызовете formset.save (commit = False), объекты не будут удалены автоматически. Вам нужно вызвать delete () для каждого из formset.deleted_objects, чтобы фактически удалить их:

С другой стороны, если вы используете простой FormSet, вы должны обработать formset.deleted_forms, возможно, в методе save () вашего formset, так как нет общего понятия о том, что означает удаление формы.

Добавление дополнительных полей в набор форм

Если вам нужно добавить дополнительные поля в форму, это может быть легко выполнено. Базовый класс formset предоставляет метод add_fields. Вы можете переопределить этот метод, чтобы добавить свои собственные поля или даже переопределить поля / атрибуты по умолчанию для полей порядка и удаления:

Передача пользовательских параметров в формы formset

Иногда ваш класс формы принимает пользовательские параметры, такие как MyArticleForm. Вы можете передать этот параметр при создании экземпляра formset:

Form_kwargs также может зависеть от конкретного экземпляра формы. Базовый класс formset предоставляет метод get_form_kwargs. Метод принимает один аргумент – индекс формы в наборе форм. Индекс None для empty_form:

Настройка префикса formset

В отображаемом HTML формы набора включают префикс для имени каждого поля. По умолчанию префикс «form», но его можно настроить с помощью аргумента префикса formset.

Например, в случае по умолчанию вы можете увидеть:

Но с ArticleFormset (prefix = ‘article’) это становится:

Это полезно, если вы хотите использовать более одного набора форм в представлении.

Использование formset в представлениях и шаблонах

Использование набора форм внутри представления мало чем отличается от использования обычного класса Form. Единственное, о чем вы хотите знать, – это обязательно использовать форму управления внутри шаблона. Смотрите пример:

Тогда шаблон будет иметь вид:

Однако есть небольшое сокращение для вышеупомянутого, позволяя самому formset иметь дело с формой управления:

Выше описывается вызов метода as_table в классе formset.

Отрисованные вручную can_delete и can_order

Если вы вручную отображаете поля в шаблоне, вы можете отобразить параметр can_delete с помощью {{form.DELETE}}:

Аналогично, если у formset есть возможность упорядочить (can_order = True), его можно отобразить с помощью {{form.ORDER}}.

Использование более одного набора форм в представлении

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

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

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