Formulaires groupés¶
Les formulaires groupés sont une couche d’abstraction pour travailler avec plusieurs formulaires sur une même page. On peut comparer cela à un tableau de données. Admettons que l’on dispose du formulaire suivant :
>>> from django import forms
>>> class ArticleForm(forms.Form):
... title = forms.CharField()
... pub_date = forms.DateField()
Il peut être souhaitable de permettre à l’utilisateur de créer plusieurs articles à la fois. Pour créer des formulaires groupés à partir d’un formulaire ArticleForm
, voici comment procéder :
>>> from django.forms import formset_factory
>>> ArticleFormSet = formset_factory(ArticleForm)
Vous avez maintenant créé un objet de formulaires groupés nommé ArticleFormSet
. Cet objet vous donne la possibilité d’effectuer une itération sur les formulaires du groupe et de les afficher tout comme vous le feriez pour un formulaire habituel :
>>> formset = ArticleFormSet()
>>> for form in formset:
... print(form.as_table())
<tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
<tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
Comme vous le voyez, un seul formulaire vierge a été affiché. Le nombre de formulaires vierges affichés dépend du paramètre extra
. Par défaut, formset_factory()
définit un seul formulaire supplémentaire ; l’exemple suivant affichera deux formulaires vierges :
>>> ArticleFormSet = formset_factory(ArticleForm, extra=2)
En itérant sur l’objet formset
, les formulaires sont affichés dans l’ordre où ils ont été créés. Vous pouvez modifier cet ordre en écrivant une implémentation différente de la méthode __iter__()
.
Il est aussi possible d’accéder aux formulaires groupés par un numéro d’index, ce qui renvoie le formulaire correspondant. Si vous surchargez __iter__
, il est aussi nécessaire de surcharger __getitem__
afin de garantir un comportement cohérent.
Données initiales pour les formulaires groupés¶
Les données initiales sont le moteur essentiel qui fait l’intérêt des formulaires groupés. Comme on peut le voir ci-dessus, vous pouvez définir le nombre de formulaires supplémentaires. Cela signifie que vous pouvez indiquer aux formulaires groupés combien de formulaires supplémentaires doivent être affichés en plus des formulaires générés à partir des données initiales. Examinons un exemple plus en détails
>>> import datetime
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, extra=2)
>>> formset = ArticleFormSet(initial=[
... {'title': 'Django is now open source',
... 'pub_date': datetime.date.today(),}
... ])
>>> for form in formset:
... print(form.as_table())
<tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Django is now open source" id="id_form-0-title" /></td></tr>
<tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-12" id="id_form-0-pub_date" /></td></tr>
<tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" id="id_form-1-title" /></td></tr>
<tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" id="id_form-1-pub_date" /></td></tr>
<tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
<tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>
Nous avons maintenant trois formulaires qui s’affichent. Un pour les données initiales que nous lui avons transmises et deux formulaires supplémentaires. Notez également que nous transmettons une liste de dictionnaires comme données initiales.
SI vous utilisez initial
dans l’affichage de formulaires groupés, vous devez passer la même valeur initial
lors du traitement de ces formulaires au moment de l’envoi des données pour permettre la détection des formulaires modifiés par l’utilisateur. Par exemple, vous pourriez avoir quelque chose comme : ArticleFormSet(request.POST, initial=[...])
.
Restriction du nombre maximum de formulaires¶
Le paramètre max_num
de formset_factory()
donne la possibilité de restreindre le nombre de formulaires que les formulaires groupés vont afficher
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, extra=2, max_num=1)
>>> formset = ArticleFormSet()
>>> for form in formset:
... print(form.as_table())
<tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
<tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
Si la valeur de max_num
est plus grande que le nombre d’objets existants dans les données initiales, un maximum de extra
formulaires vierges supplémentaires seront ajoutés au formulaire groupé, tant que le nombre total de formulaires n’excède pas max_num
. Par exemple, si extra=2
et max_num=2
et que le formulaire groupé est initialisé avec un élément initial
, on verra s’afficher un formulaire pour l’élément initial et un formulaire vierge.
Si le nombre d’éléments dans les données initiales dépasse max_num
, tous les formulaires correspondant aux données initiales seront affichés quelle que soit la valeur de max_num
et aucun formulaire supplémentaire ne sera affiché. Par exemple, si extra=3
et max_num=1
et que le formulaire groupé est initialisé avec deux éléments, ce sont deux formulaires avec les données initiales qui seront affichés.
Une valeur max_num
None
(par défaut) place une limite élevée du nombre de formulaires affichés (1000). En pratique, cela équivaut à aucune limite.
Par défaut, max_num
ne s’applique qu’au nombre de formulaires affichés et non pas à la validation. Si validate_max=True
est transmis à formset_factory()
, max_num
s’applique alors à la validation. Voir validate_max.
Validation des formulaires groupés¶
La validation des formulaires groupés est presque identique à celle d’un formulaire Form
normal. L’objet de formulaires groupés contient une méthode is_valid
afin de fournir une manière agile de valider tous les formulaires du groupe :
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm)
>>> data = {
... 'form-TOTAL_FORMS': '1',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
True
Nous n’avons fourni aucune donnée aux formulaires groupés ce qui aboutit à un formulaire valide. Les formulaires groupés sont assez intelligents pour ne pas prendre en compte des formulaires supplémentaires qui n’ont pas été modifiés. Si nous passons un article non valable :
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test',
... 'form-1-pub_date': '', # <-- this date is missing but required
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {'pub_date': ['This field is required.']}]
Comme on peut le voir, formset.errors
est une liste composée d’éléments correspondants à chaque formulaire du groupe. La validation s’est faite pour chacun des deux formulaires, et le message d’erreur attendu apparaît pour le second.
Tout comme pour l’utilisation de formulaires normaux, chaque champ de formulaire groupé peut inclure des attributs HTML tels que maxlength
pour la validation par le navigateur. Cependant, les champs de formulaires groupés n’incluront pas l’attribut required
car cette validation pourrait être incorrecte lors de l’ajout ou de la suppression de formulaires.
Pour contrôler le nombre d’erreurs dans les formulaires groupés, nous pouvons utiliser la méthode total_error_count
:
>>> # Using the previous example
>>> formset.errors
[{}, {'pub_date': ['This field is required.']}]
>>> len(formset.errors)
2
>>> formset.total_error_count()
1
Nous pouvons aussi vérifier si les données des formulaires diffèrent des données initiales (c’est-à-dire si le formulaire a été envoyé sans aucune donnée) :
>>> data = {
... 'form-TOTAL_FORMS': '1',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': '',
... 'form-0-pub_date': '',
... }
>>> formset = ArticleFormSet(data)
>>> formset.has_changed()
False
Rôle du formulaire de gestion (ManagementForm
)¶
Vous avez peut-être remarqué les données supplémentaires (form-TOTAL_FORMS
, form-INITIAL_FORMS
et form-MAX_NUM_FORMS
) qui étaient requises dans les données de formulaires groupés ci-dessus. Ces données sont exigées par le formulaire de gestion. Celui-ci est utilisé par les formulaires groupés pour gérer l’ensemble des formulaires contenus dans le groupe. Si vous ne fournissez pas ces données de gestion, une exception sera générée :
>>> data = {
... 'form-0-title': 'Test',
... 'form-0-pub_date': '',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
Traceback (most recent call last):
...
django.forms.utils.ValidationError: ['ManagementForm data is missing or has been tampered with']
Ces données servent à conserver la trace du nombre d’instances de formulaires qui sont affichées. Si vous ajoutez de nouveaux formulaires par JavaScript, il est aussi nécessaire d’incrémenter les champs de comptage de ce formulaire. D’un autre côté, si vous utilisez JavaScript pour permettre la suppression d’objets existants, vous devez alors vous assurer que ceux qui sont supprimés soient correctement marqués comme « à supprimer » en incluant le paramètre form-#-DELETE
dans les données d’envoi POST
. Il est prévu que tous les formulaires soient présents dans les données POST
quoi qu’il arrive.
Le formulaire de gestion est disponible sous forme d’attribut de l’objet de formulaires groupés. Lorsque vous affichez des formulaires groupés dans un gabarit, vous pouvez inclure toutes les données de gestion en affichant {{ my_formset.management_form }}
(en remplaçant le nom de vos formulaires groupés en conséquence).
total_form_count
et initial_form_count
¶
BaseFormSet
possède quelques méthodes étroitement liées aux données total_form_count
et initial_form_count
du formulaire de gestion ManagementForm
.
total_form_count
renvoie le nombre total de formulaires du groupe de formulaires. initial_form_count
renvoie le nombre de formulaires du groupe qui ont été pré-remplis et est également utilisé pour déterminer le nombre de formulaires requis. Vous n’aurez probablement jamais à surcharger l’une de ces méthodes, mais prenez garde à bien comprendre ce qu’elles font si vous deviez le faire.
empty_form
¶
BaseFormSet
fournit un attribut supplémentaire empty_form
qui renvoie une instance de formulaire avec le préfixe __prefix__
pour faciliter l’utilisation de formulaires dynamiques avec JavaScript.
Validation personnalisée des formulaires groupés¶
Les formulaires groupés ont une méthode clean
similaire à celle d’une classe Form
. C’est là que vous pouvez définir votre propre validation agissant au niveau des formulaires groupés :
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> class BaseArticleFormSet(BaseFormSet):
... def clean(self):
... """Checks that no two articles have the same title."""
... if any(self.errors):
... # Don't bother validating the formset unless each form is valid on its own
... return
... titles = []
... for form in self.forms:
... title = form.cleaned_data['title']
... if title in titles:
... raise forms.ValidationError("Articles in a set must have distinct titles.")
... titles.append(title)
>>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test',
... 'form-1-pub_date': '1912-06-23',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {}]
>>> formset.non_form_errors()
['Articles in a set must have distinct titles.']
La méthode clean
des formulaires groupés est appelée après les méthodes Form.clean
des formulaires individuels. Les erreurs produites à ce niveau sont accessibles par la méthode non_form_errors()
sur l’objet des formulaires groupés.
Validation du nombre de formulaires dans les formulaires groupés¶
Django fournit plusieurs manières de valider le nombre minimum ou maximum de formulaires soumis. Les applications ayant besoin d’une validation plus adaptée du nombre de formulaires peuvent utiliser la validation personnalisée de formulaires groupés.
validate_max
¶
Si validate_max=True
est transmis à formset_factory()
, la validation vérifiera également que le nombre de formulaires dans les données reçues moins ceux marqués pour la suppression ne dépasse pas max_num
.
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, max_num=1, validate_max=True)
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MIN_NUM_FORMS': '',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test 2',
... 'form-1-pub_date': '1912-06-23',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {}]
>>> formset.non_form_errors()
['Please submit 1 or fewer forms.']
validate_max=True
valide strictement la valeur de max_num
, même si cette valeur a été dépassée en raison d’un nombre de données initiales trop important.
Note
Quelle que soit la valeur de validate_max
, si le nombre de formulaires dans un jeu de données dépasse max_num
de plus de 1000, la validation du formulaire échoue comme si validate_max
avait été défini ; de plus, seuls les 1000 premiers formulaires dépassant max_num
seront validés. Tout le reste est purement ignoré. Il s’agit d’une mesure de protection contre les attaques de remplissage de mémoire employant des requêtes POST
contrefaites.
validate_min
¶
Si validate_min=True
est passé à formset_factory()
, la validation vérifiera également que le nombre de formulaires dans les données reçues moins ceux marqués pour la suppression est supérieur ou égal à min_num
.
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, min_num=3, validate_min=True)
>>> data = {
... 'form-TOTAL_FORMS': '2',
... 'form-INITIAL_FORMS': '0',
... 'form-MIN_NUM_FORMS': '',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Test',
... 'form-0-pub_date': '1904-06-16',
... 'form-1-title': 'Test 2',
... 'form-1-pub_date': '1912-06-23',
... }
>>> formset = ArticleFormSet(data)
>>> formset.is_valid()
False
>>> formset.errors
[{}, {}]
>>> formset.non_form_errors()
['Please submit 3 or more forms.']
Tri et suppression de formulaires¶
La méthode formset_factory()
fournit deux paramètres facultatifs can_order
et can_delete
pour faciliter le tri et la suppression de formulaires dans des formulaires groupés.
can_order
¶
-
BaseFormSet.
can_order
¶
Valeur par défaut : False
Ce paramètre permet de créer des formulaires groupés qui peuvent être triés :
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, can_order=True)
>>> formset = ArticleFormSet(initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> for form in formset:
... print(form.as_table())
<tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
<tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-10" id="id_form-0-pub_date" /></td></tr>
<tr><th><label for="id_form-0-ORDER">Order:</label></th><td><input type="number" name="form-0-ORDER" value="1" id="id_form-0-ORDER" /></td></tr>
<tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" value="Article #2" id="id_form-1-title" /></td></tr>
<tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" value="2008-05-11" id="id_form-1-pub_date" /></td></tr>
<tr><th><label for="id_form-1-ORDER">Order:</label></th><td><input type="number" name="form-1-ORDER" value="2" id="id_form-1-ORDER" /></td></tr>
<tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
<tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>
<tr><th><label for="id_form-2-ORDER">Order:</label></th><td><input type="number" name="form-2-ORDER" id="id_form-2-ORDER" /></td></tr>
Ceci ajoute un champ supplémentaire à chaque formulaire. Ce nouveau champ s’appelle ORDER
et est de type forms.IntegerField
. Pour les formulaires générés à partir des données initiales, ces champs reçoivent automatiquement une valeur numérique. Voyons ce qui se passe si l’utilisateur modifie ces valeurs :
>>> data = {
... 'form-TOTAL_FORMS': '3',
... 'form-INITIAL_FORMS': '2',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Article #1',
... 'form-0-pub_date': '2008-05-10',
... 'form-0-ORDER': '2',
... 'form-1-title': 'Article #2',
... 'form-1-pub_date': '2008-05-11',
... 'form-1-ORDER': '1',
... 'form-2-title': 'Article #3',
... 'form-2-pub_date': '2008-05-01',
... 'form-2-ORDER': '0',
... }
>>> formset = ArticleFormSet(data, initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> formset.is_valid()
True
>>> for form in formset.ordered_forms:
... print(form.cleaned_data)
{'pub_date': datetime.date(2008, 5, 1), 'ORDER': 0, 'title': 'Article #3'}
{'pub_date': datetime.date(2008, 5, 11), 'ORDER': 1, 'title': 'Article #2'}
{'pub_date': datetime.date(2008, 5, 10), 'ORDER': 2, 'title': 'Article #1'}
can_delete
¶
-
BaseFormSet.
can_delete
¶
Valeur par défaut : False
Ce paramètre permet de créer des formulaires groupés où l’on peut choisir des formulaires à supprimer :
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> ArticleFormSet = formset_factory(ArticleForm, can_delete=True)
>>> formset = ArticleFormSet(initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> for form in formset:
... print(form.as_table())
<tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
<tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-10" id="id_form-0-pub_date" /></td></tr>
<tr><th><label for="id_form-0-DELETE">Delete:</label></th><td><input type="checkbox" name="form-0-DELETE" id="id_form-0-DELETE" /></td></tr>
<tr><th><label for="id_form-1-title">Title:</label></th><td><input type="text" name="form-1-title" value="Article #2" id="id_form-1-title" /></td></tr>
<tr><th><label for="id_form-1-pub_date">Pub date:</label></th><td><input type="text" name="form-1-pub_date" value="2008-05-11" id="id_form-1-pub_date" /></td></tr>
<tr><th><label for="id_form-1-DELETE">Delete:</label></th><td><input type="checkbox" name="form-1-DELETE" id="id_form-1-DELETE" /></td></tr>
<tr><th><label for="id_form-2-title">Title:</label></th><td><input type="text" name="form-2-title" id="id_form-2-title" /></td></tr>
<tr><th><label for="id_form-2-pub_date">Pub date:</label></th><td><input type="text" name="form-2-pub_date" id="id_form-2-pub_date" /></td></tr>
<tr><th><label for="id_form-2-DELETE">Delete:</label></th><td><input type="checkbox" name="form-2-DELETE" id="id_form-2-DELETE" /></td></tr>
Un peu comme pour can_order
, ce paramètre ajoute un nouveau champ DELETE
de type forms.BooleanField
à chaque formulaire. Lorsque les données reviennent et que certains de ces champs ont une valeur « vrai », il est possible d’accéder aux formulaires concernés avec deleted_forms
:
>>> data = {
... 'form-TOTAL_FORMS': '3',
... 'form-INITIAL_FORMS': '2',
... 'form-MAX_NUM_FORMS': '',
... 'form-0-title': 'Article #1',
... 'form-0-pub_date': '2008-05-10',
... 'form-0-DELETE': 'on',
... 'form-1-title': 'Article #2',
... 'form-1-pub_date': '2008-05-11',
... 'form-1-DELETE': '',
... 'form-2-title': '',
... 'form-2-pub_date': '',
... 'form-2-DELETE': '',
... }
>>> formset = ArticleFormSet(data, initial=[
... {'title': 'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': 'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
... ])
>>> [form.cleaned_data for form in formset.deleted_forms]
[{'DELETE': True, 'pub_date': datetime.date(2008, 5, 10), 'title': 'Article #1'}]
Si vous utilisez un ModelFormSet
, les instances de modèle correspondant aux formulaires supprimés seront supprimées lorsque formset.save ()
sera appelée.
Si vous appelez formset.save(commit=False)
, les objets ne seront pas supprimés automatiquement. Vous devrez appeler delete()
pour chacun des formset.deleted_objects
afin que la suppression soit effective :
>>> instances = formset.save(commit=False)
>>> for obj in formset.deleted_objects:
... obj.delete()
D’autre part, si vous utilisez un FormSet
simple, c’est à vous de gérer formset.deleted_forms
, par exemple dans la méthode save()
de votre formulaire groupé, car il n’existe pas de notion générale sur ce qu’implique la suppression d’un formulaire.
Ajout de champs supplémentaires à des formulaires groupés¶
L’ajout de champs supplémentaires aux formulaires groupés est simple à effectuer. La classe de base des formulaires groupés offre une méthode add_fields
. Vous pouvez simplement surcharger cette méthode pour ajouter vos propres champs ou même pour redéfinir les champs/attributs par défaut des champs de tri et de suppression :
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> class BaseArticleFormSet(BaseFormSet):
... def add_fields(self, form, index):
... super(BaseArticleFormSet, self).add_fields(form, index)
... form.fields["my_field"] = forms.CharField()
>>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
>>> formset = ArticleFormSet()
>>> for form in formset:
... print(form.as_table())
<tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
<tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
<tr><th><label for="id_form-0-my_field">My field:</label></th><td><input type="text" name="form-0-my_field" id="id_form-0-my_field" /></td></tr>
Transmission de paramètres personnalisés aux formulaires de jeux de formulaires¶
Il arrive parfois qu’une classe de formulaire accepte des paramètres personnalisés, comme MyArticleForm
. Vous pouvez transmettre ce paramètre lors de l’instanciation du jeu de formulaires :
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> from myapp.forms import ArticleForm
>>> class MyArticleForm(ArticleForm):
... def __init__(self, *args, **kwargs):
... self.user = kwargs.pop('user')
... super(MyArticleForm, self).__init__(*args, **kwargs)
>>> ArticleFormSet = formset_factory(MyArticleForm)
>>> formset = ArticleFormSet(form_kwargs={'user': request.user})
Le paramètre form_kwargs
peut aussi dépendre de l’instance de formulaire spécifique. La classe de base du jeu de formulaires fournit une méthode get_form_kwargs
. Celle-ci accepte un seul paramètre, l’indice du formulaire dans le jeu de formulaire. Cet indice vaut None
pour le formulaire vide empty_form:
>>> from django.forms import BaseFormSet
>>> from django.forms import formset_factory
>>> class BaseArticleFormSet(BaseFormSet):
... def get_form_kwargs(self, index):
... kwargs = super(BaseArticleFormSet, self).get_form_kwargs(index)
... kwargs['custom_kwarg'] = index
... return kwargs
Utilisation des formulaires groupés dans les vues et les gabarits¶
L’utilisation de formulaires groupés dans une vue est aussi simple que l’utilisation d’une classe Form
habituelle. La seule chose à laquelle il faut être attentif est de ne pas oublier d’inclure le formulaire de gestion dans le gabarit. Examinons un exemple de vue :
from django.forms import formset_factory
from django.shortcuts import render
from myapp.forms import ArticleForm
def manage_articles(request):
ArticleFormSet = formset_factory(ArticleForm)
if request.method == 'POST':
formset = ArticleFormSet(request.POST, request.FILES)
if formset.is_valid():
# do something with the formset.cleaned_data
pass
else:
formset = ArticleFormSet()
return render(request, 'manage_articles.html', {'formset': formset})
Le gabarit manage_articles.html
pourrait ressembler à ceci :
<form method="post" action="">
{{ formset.management_form }}
<table>
{% for form in formset %}
{{ form }}
{% endfor %}
</table>
</form>
Toutefois, le code ci-dessus peut être légèrement raccourci en laissant les formulaires groupés se charger eux-mêmes du formulaire de gestion :
<form method="post" action="">
<table>
{{ formset }}
</table>
</form>
Le résultat du code ci-dessus est que la classe de formulaires groupés va appeler sa méthode as_table
.
Affichage manuel de can_delete
et can_order
¶
Si vous affichez manuellement les champs dans le gabarit, vous pouvez afficher le paramètre can_delete
avec {{ form.DELETE }}
:
<form method="post" action="">
{{ formset.management_form }}
{% for form in formset %}
<ul>
<li>{{ form.title }}</li>
<li>{{ form.pub_date }}</li>
{% if formset.can_delete %}
<li>{{ form.DELETE }}</li>
{% endif %}
</ul>
{% endfor %}
</form>
De la même façon, si les formulaires groupés peuvent être triés (can_order=True
), il est possible d’afficher le champ de tri avec {{ form.ORDER }}
.
Utilisation de plus d’un objet de formulaires groupés dans une vue¶
Il est possible d’utiliser plus d’un objet de formulaires groupés dans une vue. Les formulaires groupés ont un comportement très semblable à celui des formulaires. Ceci dit, vous pouvez utiliser l’attribut prefix
afin de préfixer les noms de champs des formulaires groupés avec une valeur donnée, ce qui permettra d’envoyer plusieurs ensembles de formulaires groupés à une vue sans conflit de nommage. Voyons un peu comment cela pourrait être fait :
from django.forms import formset_factory
from django.shortcuts import render
from myapp.forms import ArticleForm, BookForm
def manage_articles(request):
ArticleFormSet = formset_factory(ArticleForm)
BookFormSet = formset_factory(BookForm)
if request.method == 'POST':
article_formset = ArticleFormSet(request.POST, request.FILES, prefix='articles')
book_formset = BookFormSet(request.POST, request.FILES, prefix='books')
if article_formset.is_valid() and book_formset.is_valid():
# do something with the cleaned_data on the formsets.
pass
else:
article_formset = ArticleFormSet(prefix='articles')
book_formset = BookFormSet(prefix='books')
return render(request, 'manage_articles.html', {
'article_formset': article_formset,
'book_formset': book_formset,
})
Les formulaires groupés seraient ensuite affichés comme d’habitude. Il est important de relever que vous devez indiquer prefix
dans tous les cas (POST
ou non), afin que l’affichage et le traitement des données puissent se faire correctement.