ModelFormLien vers cette rubrique#Si vous construisez une application basée sur une base de données, il y a des chances pour que vos formulaires correspondent étroitement avec les modèles Django. Par exemple, vous pourriez avoir un modèle BlogComment et vouloir créer un formulaire permettant d’envoyer des commentaires. Dans ce cas, il serait redondant de devoir définir les types de champs du formulaire, car vous avez déjà défini des champs au niveau du modèle.
C’est pour cette raison que Django fournit une classe utilitaire permettant de créer une classe de formulaire Form à partir d’un modèle Django.
Par exemple :
\n>>> from django.forms import ModelForm\n>>> from myapp.models import Article\n\n# Create the form class.\n>>> class ArticleForm(ModelForm):\n... class Meta:\n... model = Article\n... fields = ["pub_date", "headline", "content", "reporter"]\n...\n\n# Creating a form to add an article.\n>>> form = ArticleForm()\n\n# Creating a form to change an existing article.\n>>> article = Article.objects.get(pk=1)\n>>> form = ArticleForm(instance=article)\nLa classe de formulaire générée contiendra un champ de formulaire pour chaque champ de modèle inclus, dans l’ordre indiqué par l’attribut fields.
Chaque champ de modèle possède un champ de formulaire par défaut. Par exemple, le champ CharField d’un modèle est représenté par un champ de formulaire CharField. Un champ ManyToManyField d’un modèle est représenté par un champ de formulaire MultipleChoiceField. Voici la liste complète des correspondances :
Champ de modèle | \nChamp de formulaire | \n
|---|---|
| \n | Non représenté dans le formulaire | \n
| \n | Non représenté dans le formulaire | \n
| \n |
| \n
| \n |
| \n
| \n |
| \n
| \n |
| \n
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n |
| \n
| \n | \n |
| \n | \n |
| \n
| \n
| \n | \n |
| \n | \n |
| \n |
| \n
| \n | \n |
| \n | \n |
| \n | \n |
| \n | \n |
| \n | Non représenté dans le formulaire | \n
| \n | \n |
| \n |
| \n
| \n | \n |
| \n | \n |
| \n | \n |
Comme l’on peut s’y attendre, les champs de modèle de type ForeignKey et ManyToManyField sont des cas spéciaux :
ForeignKey est représenté par django.forms.ModelChoiceField, qui est un champ ChoiceField dont les choix possibles sont définis par le QuerySet d’un modèle.
ManyToManyField est représenté par un django.forms.ModelMultipleChoiceField, qui est un champ MultipleChoiceField dont les choix possibles sont définis par le QuerySet d’un modèle.
De plus, chaque champ de formulaire généré possède les attributs comme suit :
\nSi le champ de modèle a blank=True, required est alors défini à False dans le champ de formulaire. Sinon, required=True.
L’étiquette (label) du champ de formulaire est défini à la valeur verbose_name du champ de modèle, avec le premier caractère en majuscules.
La valeur help_text du champ de formulaire est définie à la valeur help_text du champ de modèle.
Si la valeur choices d’un champ de modèle est définie, le composant ( widget) du champ de formulaire sera de type Select dont les choix proviendront de la valeur choices du champ de modèle. Ces choix incluent normalement le choix vierge qui est sélectionné par défaut. Si le champ est obligatoire, cela force l’utilisateur à faire un choix. Le choix vierge n’est pas inclus si le champ de modèle a blank=False ainsi qu’une valeur par défaut (default) explicite (c’est la valeur default qui sera initialement sélectionnée).
Pour terminer, notez que vous pouvez surcharger le champ de formulaire utilisé pour un champ de modèle donné. Consultez Surcharge des champs par défaut ci-dessous.
\nConsidérez cet ensemble de modèles :
\nfrom django.db import models\nfrom django.forms import ModelForm\n\nTITLE_CHOICES = {\n "MR": "Mr.",\n "MRS": "Mrs.",\n "MS": "Ms.",\n}\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n title = models.CharField(max_length=3, choices=TITLE_CHOICES)\n birth_date = models.DateField(blank=True, null=True)\n\n def __str__(self):\n return self.name\n\n\nclass Book(models.Model):\n name = models.CharField(max_length=100)\n authors = models.ManyToManyField(Author)\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title", "birth_date"]\n\n\nclass BookForm(ModelForm):\n class Meta:\n model = Book\n fields = ["name", "authors"]\nAvec ces modèles, les sous-classes ModelForm ci-dessus seraient à peu près équivalentes à ceci (avec comme seule différence la méthode save() que nous aborderons dans un moment) :
from django import forms\n\n\nclass AuthorForm(forms.Form):\n name = forms.CharField(max_length=100)\n title = forms.CharField(\n max_length=3,\n widget=forms.Select(choices=TITLE_CHOICES),\n )\n birth_date = forms.DateField(required=False)\n\n\nclass BookForm(forms.Form):\n name = forms.CharField(max_length=100)\n authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())\nModelFormLien vers cette rubrique#La validation d’un ModelForm se distingue en deux étapes importantes :
Comme pour la validation de formulaire normale, la validation des formulaires de modèle est déclenchée implicitement lors de l’appel à is_valid() ou par l’accession à l’attribut errors, ou explicitement en appelant full_clean(), même si en pratique cette dernière méthode est rarement utilisée.
La validation des modèles est déclenchée à partir de l’étape de validation de formulaire, juste après l’appel à la fonction clean() du formulaire. En premier, la méthode full_clean() du modèle est appelée avec validate_unique=False et validate_constraints=False, puis ce sont les méthodes validate_unique() et validate_constraints() qui sont appelées dans cet ordre.
clean()Lien vers cette rubrique#Vous pouvez surcharger la méthode clean() d’un formulaire de modèle pour procéder à des validations supplémentaires de la même manière que pour un formulaire normal.
Une instance de formulaire de modèle liée à un objet modèle contient un attribut instance qui donne à ses méthodes l’accès à cette instance de modèle spécifique.
Dans le cadre du processus de validation, ModelForm appelle la méthode clean() de chaque champ du modèle possédant un champ de formulaire correspondant. Si vous avez exclu des champs de modèle, la validation ne sera pas effectuée pour ces champs. Consultez la documentation de la validation des formulaires pour en savoir plus sur le fonctionnement du nettoyage et de la validation des champs.
La méthode clean() du modèle est appelée avant les contrôles d’unicité et de contraintes. Consultez la validation des objets pour plus d’informations sur la méthode clean() des modèles.
Les messages d’erreur définis au niveau des champs de formulaire ou au niveau de la classe Meta de formulaire ont toujours la priorité sur les messages d’erreur définis au niveau des champs de modèle.
Les messages d’erreur définis au niveau des champs de modèle ne sont utilisés que lorsqu’une erreur ValidationError est générée à l’étape de validation du modèle et qu’aucun message d’erreur correspondant n’est défini au niveau du formulaire.
Vous pouvez surcharger les messages d’erreur issus de NON_FIELD_ERRORS et générés par la validation des modèles en ajoutant la clé NON_FIELD_ERRORS au dictionnaire error_messages de la classe Meta interne des classes ModelForm:
from django.core.exceptions import NON_FIELD_ERRORS\nfrom django.forms import ModelForm\n\n\nclass ArticleForm(ModelForm):\n class Meta:\n error_messages = {\n NON_FIELD_ERRORS: {\n "unique_together": "%(model_name)s's %(field_labels)s are not unique.",\n }\n }\nsave()Lien vers cette rubrique#Chaque ModelForm possède aussi une méthode save(). Celle-ci crée et enregistre un objet en base de données à partir des données saisies dans le formulaire. Une sous-classe de ModelForm peut accepter une instance existante de modèle par le paramètre nommé instance. Si celui-ci est présent, save() met à jour cette instance. Dans le cas contraire, save() crée une nouvelle instance du modèle concerné :
>>> from myapp.models import Article\n>>> from myapp.forms import ArticleForm\n\n# Create a form instance from POST data.\n>>> f = ArticleForm(request.POST)\n\n# Save a new Article object from the form's data.\n>>> new_article = f.save()\n\n# Create a form to edit an existing Article, but use\n# POST data to populate the form.\n>>> a = Article.objects.get(pk=1)\n>>> f = ArticleForm(request.POST, instance=a)\n>>> f.save()\nNotez que si le formulaire n’a pas été validé, l’appel à save() s’en occupera en contrôlant form.errors. Une erreur ValueError est générée si les données du formulaire ne sont pas valides, par exemple si form.errors est évalué à True.
Si un champ facultatif ne figure pas dans les données de formulaire, l’instance de modèle résultante utilise comme valeur de champ le contenu default du champ de modèle, si elle est définie. Ce comportement ne s’applique pas aux champs qui utilisent CheckboxInput, CheckboxSelectMultiple ou SelectMultiple (ou tout autre composant personnalisé dont la méthode value_omitted_from_data() renvoie toujours False) dans la mesure où une case à cocher non cochée ou des <select multiple> non sélectionnés ne sont pas inclus dans l’envoi des données d’un formulaire HTML. Utilisez un champ ou un composant de formulaire personnalisé si vous concevez une API et que vous souhaitez obtenir le comportement de valeur par défaut de base pour un champ qui utilise l’un de ces composants.
Cette méthode save() accepte un paramètre nommé facultatif commit, qui accepte les valeurs True ou False. Si vous appelez save() avec commit=False, elle renvoie un objet qui n’aura pas encore été enregistré dans la base de données. Dans ce cas, c’est à vous d’appeler save() sur l’instance de modèle obtenue. C’est utile lorsque vous souhaitez effectuer un traitement particulier sur l’objet avant qu’il soit enregistré, ou si vous voulez utiliser l’une des options d’enregistrement de modèle spécialisées. commit vaut True par défaut.
Un autre effet de bord de l’utilisation de commit=False se voit lorsque le modèle possède une relation plusieurs-à-plusieurs vers un autre modèle. Dans ce cas, Django ne peut pas enregistrer immédiatement les données du formulaire de la relation plusieurs-à-plusieurs. La raison est qu’il n’est pas possible d’enregistrer des données plusieurs-à-plusieurs propres à une instance si celle-ci n’existe pas encore dans la base de données.
Pour contourner ce problème, chaque fois que vous enregistrez un formulaire avec commit=False, Django ajoute une méthode save_m2m() à la sous-classe de votre ModelForm. Après avoir manuellement enregistré l’instance dérivée du formulaire, vous pouvez appeler save_m2m() pour enregistrer les données de formulaire de type plusieurs-à-plusieurs. Par exemple :
# Create a form instance with POST data.\n>>> f = AuthorForm(request.POST)\n\n# Create, but don't save the new author instance.\n>>> new_author = f.save(commit=False)\n\n# Modify the author in some way.\n>>> new_author.some_field = "some_value"\n\n# Save the new instance.\n>>> new_author.save()\n\n# Now, save the many-to-many data for the form.\n>>> f.save_m2m()\nIl n’est utile d’appeler save_m2m() que si vous utilisez save(commit=False). Lorsque vous appelez la méthode save() d’un formulaire, toutes les données, y compris les données plusieurs-à-plusieurs, sont enregistrées sans avoir besoin de faire quoi que ce soit d’autre. Par exemple :
# Create a form instance with POST data.\n>>> a = Author()\n>>> f = AuthorForm(request.POST, instance=a)\n\n# Create and save the new author instance. There's no need to do anything else.\n>>> new_author = f.save()\nÀ part les méthodes save() et save_m2m(), un ModelForm fonctionne exactement de la même manière que tout autre formulaire forms. Par exemple, la méthode is_valid() est utilisée pour vérifier la validité, la méthode is_multipart() est utilisée pour déterminer si un formulaire nécessite un envoi de fichier multipart (et donc que request.FILES doit être transmis au formulaire), etc. Voir Liaison de fichiers téléversés avec un formulaire pour plus d’informations.
Il est fortement recommandé de définir explicitement tous les champs qui doivent être présents dans le formulaire en utilisant l’attribut fields. Si vous ne le faites pas, cela peut facilement devenir source de problèmes de sécurité lorsqu’un formulaire permet à un utilisateur de définir certains champs de manière non prévue, particulièrement lorsqu’on ajoute de nouveaux champs à un modèle. En fonction de la façon dont le formulaire est affiché, il est même possible que le problème ne soit pas visible sur la page Web.
Une autre approche est d’inclure automatiquement tous les champs ou d’en exclure certains. Mais à la base, cette approche est notoirement moins sécurisée et a déjà abouti à des failles sévères sur des sites web célèbres (par ex. GitHub).
\nIl existe toutefois deux raccourcis disponibles pour les cas où vous pouvez garantir que ces questions de sécurité ne s’appliquent pas à votre situation :
\nDéfinir l’attribut fields à la valeur spéciale '__all__' pour indiquer que tous les champs du modèle doivent être utilisés. Par exemple :
from django.forms import ModelForm\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = "__all__"\nDéfinir l’attribut exclude de la classe interne Meta du ModelForm à une liste de champs à exclure du formulaire.
Par exemple :
\nclass PartialAuthorForm(ModelForm):\n class Meta:\n model = Author\n exclude = ["title"]\nComme le modèle Author possède les trois champs name, title et birth_date, nous nous retrouvons avec les champs name et birth_date affichés dans le formulaire.
Si l’une de ces techniques est employée, l’ordre d’apparition des champs dans le formulaire respecte l’ordre de définition des champs du modèle, avec les instances ManyToManyField apparaissant en dernier.
De plus, Django applique la règle suivante : si vous définissez editable=False au niveau du champ de modèle, tout formulaire créé à partir du modèle via ModelForm ne contiendra pas ce champ.
Les types de champs par défaut, tels que décrits dans le tableau ci-dessus Types de champs, sont des choix raisonnables. Si votre modèle contient un champ DateField, il est probable que vous vouliez représenter ce champ dans un formulaire par un champ de formulaire DateField. Mais ModelForm apporte la souplesse de pouvoir modifier le champ de formulaire pour un modèle défini.
Pour indiquer un composant personnalisé pour un champ, utilisez l’attribut widgets de la classe Meta interne. Ce doit être un dictionnaire faisant correspondre les noms de champs à des classes ou des instances de composants.
Par exemple, si vous voulez que le champ CharField de l’attribut name du modèle Author soit représenté par un composant <textarea> au lieu du composant <input type="text"> par défaut, vous pouvez surcharger le composant du champ :
from django.forms import ModelForm, Textarea\nfrom myapp.models import Author\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title", "birth_date"]\n widgets = {\n "name": Textarea(attrs={"cols": 80, "rows": 20}),\n }\nLe dictionnaire widgets accepte soit des instances de composants (par ex. Textarea(...)) ou des classes (par ex. Textarea). Notez que le dictionnaire widgets est ignoré pour les champs de modèles ayant un attribut choices non vide. Dans ce cas, vous devez surcharger le champ de formulaire pour indiquer un composant widget différent.
De la même façon, vous pouvez indiquer les attributs labels, help_texts et error_messages de la classe interne Meta si vous avez besoin de personnaliser davantage un champ.
Par exemple, si vous souhaitez personnaliser la formulation de tous les textes visibles pour l’utilisateur concernant le champ name:
from django.utils.translation import gettext_lazy as _\n\n\nclass AuthorForm(ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title", "birth_date"]\n labels = {\n "name": _("Writer"),\n }\n help_texts = {\n "name": _("Some useful help text."),\n }\n error_messages = {\n "name": {\n "max_length": _("This writer's name is too long."),\n },\n }\nVous pouvez aussi indiquer field_classes ou formfield_callback pour personnaliser le type des champs créés par le formulaire.
Par exemple, si vous souhaitez utiliser MySlugFormField pour le champ slug, vous pourriez procéder ainsi :
from django.forms import ModelForm\nfrom myapp.models import Article\n\n\nclass ArticleForm(ModelForm):\n class Meta:\n model = Article\n fields = ["pub_date", "headline", "content", "reporter", "slug"]\n field_classes = {\n "slug": MySlugFormField,\n }\nou :
\nfrom django.forms import ModelForm\nfrom myapp.models import Article\n\n\ndef formfield_for_dbfield(db_field, **kwargs):\n if db_field.name == "slug":\n return MySlugFormField()\n return db_field.formfield(**kwargs)\n\n\nclass ArticleForm(ModelForm):\n class Meta:\n model = Article\n fields = ["pub_date", "headline", "content", "reporter", "slug"]\n formfield_callback = formfield_for_dbfield\nFinalement, si vous souhaitez contrôler complètement un champ, y compris son type, ses validateurs, son caractère obligatoire, etc., vous pouvez le faire en définissant les champs de manière déclarative comme on le ferait pour un formulaire Form normal.
Si vous souhaitez indiquer les validateurs d’un champ, vous pouvez le faire en définissant le champ de manière déclarative et en indiquant le paramètre validators:
from django.forms import CharField, ModelForm\nfrom myapp.models import Article\n\n\nclass ArticleForm(ModelForm):\n slug = CharField(validators=[validate_slug])\n\n class Meta:\n model = Article\n fields = ["pub_date", "headline", "content", "reporter", "slug"]\nPar défaut, les champs d’un ModelForm ne régionalisent pas leurs données. Pour activer cette régionalisation, vous pouvez utiliser l’attribut localized_fields de la classe Meta.
>>> from django.forms import ModelForm\n>>> from myapp.models import Author\n>>> class AuthorForm(ModelForm):\n... class Meta:\n... model = Author\n... localized_fields = ['birth_date']\nSi localized_fields est défini à la valeur spéciale '__all__', les valeurs de tous les champs seront régionalisées.
Comme pour les formulaires de base, il est possible d’étendre et de réutiliser les classes ModelForm par l’héritage. C’est utile lorsque vous devez déclarer des champs ou des méthodes supplémentaires dans une sous-classe pour les utiliser dans des formulaires dérivés de modèles. Par exemple, en utilisant la classe ArticleForm présentée précédemment :
>>> class EnhancedArticleForm(ArticleForm):\n... def clean_pub_date(self): ...\n...\nCela crée un formulaire qui se comporte comme ArticleForm, à l’exception de certaines validations et nettoyages supplémentaires pour le champ pub_date.
Il est aussi possible d’hériter de la classe Meta interne du parent si vous avez besoin de modifier les listes Meta.fields ou Meta.exclude:
>>> class RestrictedArticleForm(EnhancedArticleForm):\n... class Meta(ArticleForm.Meta):\n... exclude = ["body"]\n...\nNous conservons ici la méthode supplémentaire de EnhancedArticleForm et enlevons un champ de la classe ArticleForm.Meta originale.
Il faut cependant relever certains points.
\nLes règles Python habituelles de la résolution de noms s’appliquent. Si vous avez plusieurs classes de base déclarant une classe interne Meta, seule la première sera considérée. C’est -à-dire la classe Meta de la sous-classe, s’il y en a une, sinon celle du premier parent, etc.
Il est possible d’hériter à la fois de Form et de ModelForm. Cependant, il faut s’assurer que ModelForm apparaisse en premier dans la chaîne MRO. Ceci parce que ces classes se basent sur des métaclasses différentes et qu’une classe ne peut posséder qu’une seule métaclasse.
Il est possible d’enlever de manière déclarative un champ Field hérité d’une classe parente en définissant son nom à None dans la sous-classe.
Cette technique n’est utilisable que pour enlever des champs qui ont eux-mêmes été définis de manière déclarative dans la classe parente ; cela n’empêchera pas la métaclasse de ModelForm de générer un champ par défaut. Pour enlever des champs par défaut, voir Sélection des champs à utiliser.
Comme avec les formulaires normaux, il est possible de spécifier les données initiales pour les formulaires en spécifiant un paramètre initial lors de l’instanciation du formulaire. Les valeurs initiales prévues de cette façon remplaceront la valeur initiale définie pour le champ et celle définie pour le modèle lié. Par exemple :
>>> article = Article.objects.get(pk=1)\n>>> article.headline\n'My headline'\n>>> form = ArticleForm(initial={"headline": "Initial headline"}, instance=article)\n>>> form["headline"].value()\n'Initial headline'\nVous pouvez créer des formulaires à partir d’un modèle donné en utilisant la fonction autonome modelform_factory() au lieu de passer par une définition de classe. Cela peut être plus pratique si vous n’avez pas à effectuer trop d’adaptations :
>>> from django.forms import modelform_factory\n>>> from myapp.models import Book\n>>> BookForm = modelform_factory(Book, fields=["author", "title"])\nCela peut également être utilisé pour faire des modifications à des formulaires existants, par exemple pour indiquer les composants à utiliser pour un certain champ :
\n>>> from django.forms import Textarea\n>>> Form = modelform_factory(Book, form=BookForm, widgets={"title": Textarea()})\nLes champs à inclure peuvent être spécifiés en utilisant les paramètres nommés fields et exclude, ou les attributs correspondants de la classe interne Meta du ModelForm. Veuillez consulter la documentation Sélection des champs à utiliser des ModelForm.
… ou pour activer la régionalisation de certains champs :
\n>>> Form = modelform_factory(Author, form=AuthorForm, localized_fields=["birth_date"])\nComme pour les formulaires groupés normaux, Django fournit quelques classes de formulaires groupés améliorées qui facilitent le travail avec les modèles Django. Réutilisons le modèle Author défini plus haut :
>>> from django.forms import modelformset_factory\n>>> from myapp.models import Author\n>>> AuthorFormSet = modelformset_factory(Author, fields=["name", "title"])\nL’utilisation de fields indique aux formulaires groupés les champs qu’ils doivent utiliser. Il est aussi possible d’utiliser une approche par exclusion, indiquant quels sont les champs à exclure :
>>> AuthorFormSet = modelformset_factory(Author, exclude=["birth_date"])\nCela crée un jeu de formulaires groupés qui sont capables de gérer les données associées au modèle Author. Le fonctionnement est le même que pour des formulaires groupés normaux :
>>> formset = AuthorFormSet()\n>>> print(formset)\n<input type="hidden" name="form-TOTAL_FORMS" value="1" id="id_form-TOTAL_FORMS"><input type="hidden" name="form-INITIAL_FORMS" value="0" id="id_form-INITIAL_FORMS"><input type="hidden" name="form-MIN_NUM_FORMS" value="0" id="id_form-MIN_NUM_FORMS"><input type="hidden" name="form-MAX_NUM_FORMS" value="1000" id="id_form-MAX_NUM_FORMS">\n<div><label for="id_form-0-name">Name:</label><input id="id_form-0-name" type="text" name="form-0-name" maxlength="100"></div>\n<div><label for="id_form-0-title">Title:</label><select name="form-0-title" id="id_form-0-title">\n<option value="" selected>---------</option>\n<option value="MR">Mr.</option>\n<option value="MRS">Mrs.</option>\n<option value="MS">Ms.</option>\n</select><input type="hidden" name="form-0-id" id="id_form-0-id"></div>\nPar défaut, lorsque vous créez des formulaires groupés à partir d’un modèle, ceux-ci utilisent un jeu de requête qui contient tous les objets du modèle (par ex. Author.objects.all()). Vous pouvez surcharger ce comportement en utilisant le paramètre queryset:
>>> formset = AuthorFormSet(queryset=Author.objects.filter(name__startswith="O"))\nComme variante, vous pouvez créer une sous-classe définissant self.queryset dans sa méthode __init__:
from django.forms import BaseModelFormSet\nfrom myapp.models import Author\n\n\nclass BaseAuthorFormSet(BaseModelFormSet):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.queryset = Author.objects.filter(name__startswith="O")\nPuis, passez votre classe BaseAuthorFormSet à la fonction de fabrique :
>>> AuthorFormSet = modelformset_factory(\n... Author, fields=["name", "title"], formset=BaseAuthorFormSet\n... )\nSi vous souhaitez renvoyer des formulaires groupés qui ne contiennent aucune instance préexistante du modèle, vous pouvez indiquer un objet QuerySet vide :
>>> AuthorFormSet(queryset=Author.objects.none())\nPar défaut, lorsque vous utilisez modelformset_factory, un formulaire de modèle est créé par modelform_factory(). Il peut souvent être utile d’indiquer un formulaire de modèle personnalisé. Par exemple, vous pouvez créer un formulaire de modèle personnalisé comportant une validation personnalisée :
class AuthorForm(forms.ModelForm):\n class Meta:\n model = Author\n fields = ["name", "title"]\n\n def clean_name(self):\n # custom validation for the name field\n ...\nPuis, indiquez ce formulaire de modèle à la fonction de fabrication :
\nAuthorFormSet = modelformset_factory(Author, form=AuthorForm)\nIl n’est pas toujours nécessaire de définir un formulaire de modèle personnalisé. La fonction modelformset_factory accepte plusieurs paramètres qui sont eux-mêmes transmis à modelform_factory et qui sont documentés plus bas.
widgetsLien vers cette rubrique#En exploitant le paramètre widgets, vous pouvez indiquer un dictionnaire de valeurs afin de personnaliser la classe de composant d’un champ particulier du ModelForm. C’est le même principe de fonctionnement que le dictionnaire widgets de la classe Meta interne d’un ModelForm:
>>> AuthorFormSet = modelformset_factory(\n... Author,\n... fields=["name", "title"],\n... widgets={"name": Textarea(attrs={"cols": 80, "rows": 20})},\n... )\nlocalized_fieldsLien vers cette rubrique#À l’aide du paramètre localized_fields, vous pouvez activer la régionalisation des champs du formulaire.
>>> AuthorFormSet = modelformset_factory(\n... Author, fields=['name', 'title', 'birth_date'],\n... localized_fields=['birth_date'])\nSi localized_fields est défini à la valeur spéciale '__all__', les valeurs de tous les champs seront régionalisées.
Comme pour les formulaires groupés normaux, il est possible de fournir des données initiales aux formulaires groupés en indiquant le paramètre initial au moment de la création de l’instance de classe de formulaires groupés de modèles renvoyée par modelformset_factory(). Cependant, avec les formulaires groupés de modèles, les valeurs initiales ne s’appliquent qu’aux formulaires supplémentaires, ceux qui ne sont pas liés à des instances d’objets existants. Si la longueur de initial dépasse le nombre de formulaires supplémentaires, les données initiales en trop sont ignorées. Si les formulaires supplémentaires avec données initiales ne sont pas modifiés par l’utilisateur, ils ne seront ni validés, ni enregistrés.
Comme pour un ModelForm, vous pouvez enregistrer les données sous forme d’objet de modèle. Cela se fait par la méthode save() des formulaires groupés :
# Create a formset instance with POST data.\n>>> formset = AuthorFormSet(request.POST)\n\n# Assuming all is valid, save the data.\n>>> instances = formset.save()\nLa méthode save() renvoie les instances qui ont été enregistrées dans la base de données. Si les données d’une instance précise n’ont pas été modifiées dans les données du formulaire, l’instance ne sera pas enregistrée dans la base de données et ne sera pas non plus incluse dans la valeur renvoyée (instances, dans l’exemple ci-dessus).
Lorsque des champs sont absents du formulaire (par exemple en raison de leur exclusion), ces champs ne sont pas modifiés par la méthode save(). Vous pouvez trouver plus d’informations sur cette restriction, qui est aussi valable pour les formulaires de modèles normaux, dans Sélection des champs à utiliser.
Passez commit=False pour recevoir les instances de modèles non enregistrées :
# don't save to the database\n>>> instances = formset.save(commit=False)\n>>> for instance in instances:\n... # do something with instance\n... instance.save()\n...\nCela vous permet de définir des données complémentaires dans les instances avant de les enregistrer dans la base de données. Si vos formulaires groupés contiennent un champ ManyToManyField, vous devrez également appeler formset.save_m2m() pour vous assurer que les liens plusieurs-à-plusieurs soient correctement enregistrés.
Après l’appel à save(), les formulaires groupés du modèle posséderont trois nouveaux attributs contenant les modifications des formulaires :
Comme pour les formulaires groupés normaux, vous pouvez utiliser les paramètres max_num et extra de modelformset_factory() pour restreindre le nombre de formulaires supplémentaires affichés.
max_num n’empêche pas les objets existants d’être affichés :
>>> Author.objects.order_by("name")\n<QuerySet [<Author: Charles Baudelaire>, <Author: Paul Verlaine>, <Author: Walt Whitman>]>\n\n>>> AuthorFormSet = modelformset_factory(Author, fields=["name"], max_num=1)\n>>> formset = AuthorFormSet(queryset=Author.objects.order_by("name"))\n>>> [x.name for x in formset.get_queryset()]\n['Charles Baudelaire', 'Paul Verlaine', 'Walt Whitman']\nDe plus, extra=0 n’empêche pas la création de nouvelles instances de modèles car il est possible d’ajouter des formulaires supplémentaires par JavaScript ou d’envoyer des données POST supplémentaires. Consultez Empêcher la création de nouveaux objets pour voir la manière de faire cela.
Si la valeur de max_num est plus grande que le nombre d’objets liés existants, un maximum de extra formulaires vierges supplémentaires seront ajoutés aux formulaires groupés, aussi longtemps que le nombre total de formulaires n’excède pas max_num:
>>> AuthorFormSet = modelformset_factory(Author, fields=["name"], max_num=4, extra=2)\n>>> formset = AuthorFormSet(queryset=Author.objects.order_by("name"))\n>>> for form in formset:\n... print(form)\n...\n<div><label for="id_form-0-name">Name:</label><input id="id_form-0-name" type="text" name="form-0-name" value="Charles Baudelaire" maxlength="100"><input type="hidden" name="form-0-id" value="1" id="id_form-0-id"></div>\n<div><label for="id_form-1-name">Name:</label><input id="id_form-1-name" type="text" name="form-1-name" value="Paul Verlaine" maxlength="100"><input type="hidden" name="form-1-id" value="3" id="id_form-1-id"></div>\n<div><label for="id_form-2-name">Name:</label><input id="id_form-2-name" type="text" name="form-2-name" value="Walt Whitman" maxlength="100"><input type="hidden" name="form-2-id" value="2" id="id_form-2-id"></div>\n<div><label for="id_form-3-name">Name:</label><input id="id_form-3-name" type="text" name="form-3-name" maxlength="100"><input type="hidden" name="form-3-id" id="id_form-3-id"></div>\nUne 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.
Avec le paramètre edit_only, il est possible d’empêcher la création de tout nouvel objet :
>>> AuthorFormSet = modelformset_factory(\n... Author,\n... fields=["name", "title"],\n... edit_only=True,\n... )\nIci, le jeu de formulaires ne fera que modifier des instances Author existantes. Aucun autre objet ne sera créé ou modifié.
Les formulaires groupés de modèle sont très semblables aux formulaires groupés normaux. Admettons que nous voulions afficher des formulaires groupés pour modifier les instances du modèle Author:
from django.forms import modelformset_factory\nfrom django.shortcuts import render\nfrom myapp.models import Author\n\n\ndef manage_authors(request):\n AuthorFormSet = modelformset_factory(Author, fields=["name", "title"])\n if request.method == "POST":\n formset = AuthorFormSet(request.POST, request.FILES)\n if formset.is_valid():\n formset.save()\n # do something.\n else:\n formset = AuthorFormSet()\n return render(request, "manage_authors.html", {"formset": formset})\nComme vous pouvez le voir, la logique de la vue de formulaires groupés de modèle n’est pas fondamentalement différente de celle de formulaires groupés normaux. La seule différence est que nous appelons formset.save() pour enregistrer les données dans la base de données (comme cela a été décrit ci-dessus dans Enregistrement des objets des formulaires groupés).
clean() d’un ModelFormSetLien vers cette rubrique#Tout comme pour un ModelForm, la méthode clean() de ModelFormSet valide par défaut qu’aucun des éléments dans les formulaires groupés ne viole les contraintes d’unicité de votre modèle (que ce soit unique, unique_together ou unique_for_date|month|year). Si vous souhaitez surcharger la méthode clean() d’un ModelFormSet et conserver cette validation, vous devez appeler la méthode clean de la classe parente :
from django.forms import BaseModelFormSet\n\n\nclass MyModelFormSet(BaseModelFormSet):\n def clean(self):\n super().clean()\n # example custom validation across forms in the formset\n for form in self.forms:\n # your custom formset validation\n ...\nNotez également qu’une fois que vous avez atteint cette étape, les instances de modèles individuelles pour chaque formulaire ont déjà été créées. Il ne suffit donc pas de modifier une valeur dans form.cleaned_data pour changer la valeur enregistrée. Si vous souhaitez modifier une valeur dans ModelFormSet.clean(), vous devez modifier form.instance:
from django.forms import BaseModelFormSet\n\n\nclass MyModelFormSet(BaseModelFormSet):\n def clean(self):\n super().clean()\n\n for form in self.forms:\n name = form.cleaned_data["name"].upper()\n form.cleaned_data["name"] = name\n # update the instance value.\n form.instance.name = name\nComme indiqué précédemment, il est possible de surcharger le jeu de requête utilisé par défaut par les formulaires groupés de modèle :
\nfrom django.forms import modelformset_factory\nfrom django.shortcuts import render\nfrom myapp.models import Author\n\n\ndef manage_authors(request):\n AuthorFormSet = modelformset_factory(Author, fields=["name", "title"])\n queryset = Author.objects.filter(name__startswith="O")\n if request.method == "POST":\n formset = AuthorFormSet(\n request.POST,\n request.FILES,\n queryset=queryset,\n )\n if formset.is_valid():\n formset.save()\n # Do something.\n else:\n formset = AuthorFormSet(queryset=queryset)\n return render(request, "manage_authors.html", {"formset": formset})\nNotez que nous transmettons le paramètre queryset à la fois aux requêtes POST et GET dans cet exemple.
Il y a trois façons d’afficher des formulaires groupés dans un gabarit Django.
\nPremièrement, vous pouvez déléguer aux formulaires groupés l’essentiel du travail :
\n<form method="post">\n {{ formset }}\n</form>\nDeuxièmement, vous pouvez afficher les formulaires groupés manuellement, mais laisser le soin à chaque formulaire de s’afficher lui-même :
\n<form method="post">\n {{ formset.management_form }}\n {% for form in formset %}\n {{ form }}\n {% endfor %}\n</form>\nLorsque vous vous occupez vous-même d’afficher les différents formulaires, prenez soin d’inclure également le formulaire de gestion comme le montre l’exemple ci-dessus. Voir la documentation du formulaire de gestion.
\nTroisièmement, vous pouvez afficher manuellement chaque champ :
\n<form method="post">\n {{ formset.management_form }}\n {% for form in formset %}\n {% for field in form %}\n {{ field.label_tag }} {{ field }}\n {% endfor %}\n {% endfor %}\n</form>\nSi vous optez pour cette troisième méthode et que vous ne bouclez pas sur les champs avec un {% for %}, vous devez aussi inclure le champ de clé primaire. Par exemple, si vous affichez les champs name et age d’un modèle :
<form method="post">\n {{ formset.management_form }}\n {% for form in formset %}\n {{ form.id }}\n <ul>\n <li>{{ form.name }}</li>\n <li>{{ form.age }}</li>\n </ul>\n {% endfor %}\n</form>\nVoyez comment nous devons explicitement afficher {{ form.id }}. Ceci pour s’assurer du bon fonctionnement des formulaires groupés de modèle, dans le cas de l’envoi POST (cet exemple suppose que la clé primaire s’appelle id. Si vous avez explicitement nommé la clé primaire su modèle autrement que id, prenez soin de l’afficher).
Les sous-formulaires groupés sont une petite couche d’abstraction au-dessus des formulaires groupés de modèle. Ils simplifient la situation où l’on manipule des objets liés au travers d’une clé étrangère. Supposons que l’on dispose de ces deux modèles :
\nfrom django.db import models\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n\n\nclass Book(models.Model):\n author = models.ForeignKey(Author, on_delete=models.CASCADE)\n title = models.CharField(max_length=100)\nSi vous voulez créer des formulaires groupés permettant de modifier les livres appartenant à un auteur particulier, vous pourriez faire ainsi :
\n>>> from django.forms import inlineformset_factory\n>>> BookFormSet = inlineformset_factory(Author, Book, fields=["title"])\n>>> author = Author.objects.get(name="Mike Royko")\n>>> formset = BookFormSet(instance=author)\nLe préfixe de BookFormSet est 'book_set' (<nom_modèle>_set ). Si la clé étrangère de Book vers Author possède l’attribut related_name, c’est ce dernier qui est utilisé.
InlineFormSetLien vers cette rubrique#Lorsque vous surchargez des méthodes de sous-formulaires groupés (InlineFormSet), il est préférable d’hériter de BaseInlineFormSet plutôt que de BaseModelFormSet.
Par exemple, si vous souhaitez surcharger clean():
from django.forms import BaseInlineFormSet\n\n\nclass CustomInlineFormSet(BaseInlineFormSet):\n def clean(self):\n super().clean()\n # example custom validation across forms in the formset\n for form in self.forms:\n # your custom formset validation\n ...\nVoir aussi Surcharge de clean() d’un ModelFormSet.
\nPuis, au moment de créer les sous-formulaires groupés, passez le paramètre facultatif formset:
>>> from django.forms import inlineformset_factory\n>>> BookFormSet = inlineformset_factory(\n... Author, Book, fields=["title"], formset=CustomInlineFormSet\n... )\n>>> author = Author.objects.get(name="Mike Royko")\n>>> formset = BookFormSet(instance=author)\nSi votre modèle contient plus d’une clé étrangère vers le même modèle, vous devrez résoudre l’ambiguïté manuellement en utilisant fk_name. Par exemple, considérez le modèle suivant :
class Friendship(models.Model):\n from_friend = models.ForeignKey(\n Friend,\n on_delete=models.CASCADE,\n related_name="from_friends",\n )\n to_friend = models.ForeignKey(\n Friend,\n on_delete=models.CASCADE,\n related_name="friends",\n )\n length_in_months = models.IntegerField()\nPour résoudre cela, vous pouvez définir fk_name dans inlineformset_factory():
>>> FriendshipFormSet = inlineformset_factory(\n... Friend, Friendship, fk_name="from_friend", fields=["to_friend", "length_in_months"]\n... )\nIl peut être nécessaire de définir une vue permettant à un utilisateur de modifier les objets liés d’un modèle. Voici comment on peut le faire :
\ndef manage_books(request, author_id):\n author = Author.objects.get(pk=author_id)\n BookInlineFormSet = inlineformset_factory(Author, Book, fields=["title"])\n if request.method == "POST":\n formset = BookInlineFormSet(request.POST, request.FILES, instance=author)\n if formset.is_valid():\n formset.save()\n # Do something. Should generally end with a redirect. For example:\n return HttpResponseRedirect(author.get_absolute_url())\n else:\n formset = BookInlineFormSet(instance=author)\n return render(request, "manage_books.html", {"formset": formset})\nNotez comment nous définissons le paramètre instance aussi bien dans le cas POST que le cas GET.
inlineformset_factory utilise modelformset_factory et transmet la plupart de ses paramètres à modelformset_factory. Cela signifie que vous pouvez utiliser le paramètre widgets tout comme vous le feriez pour modelformset_factory. Voir Indication des composants de formulaire à utiliser avec widgets ci-dessus.