L’API du rendu des formulaires¶
Les composants de formulaires de Django sont produits en utilisant le système des moteurs de gabarit de Django.
Le processus de production des formulaires peut être personnalisé à plusieurs niveaux :
- Les composants peuvent indiquer des noms de gabarit personnalisés.
- Les formulaires et les composants peuvent indiquer des classes de moteur de rendu personnalisées.
- Un gabarit de composant peut être surchargé par projet. (Les applications réutilisables ne devraient typiquement pas surcharger les gabarits de base car cela pourrait générer des conflits avec les gabarits personnalisés d’un projet.)
L’API de rendu de bas niveau¶
Le processus de rendu des gabarits de formulaires est contrôlé par une classe de rendu personnalisable. Cette classe peut être indiquée en définissant le réglage FORM_RENDERER
. Par défaut, il contient '
django.forms.renderers.DjangoTemplates
'
.
By specifying a custom form renderer and overriding
form_template_name
you can adjust the default form
markup across your project from a single place.
You can also provide a custom renderer per-form or per-widget by setting the
Form.default_renderer
attribute or by using the renderer
argument
of Form.render()
, or Widget.render()
.
Matching points apply to formset rendering. See Utilisation des formulaires groupés dans les vues et les gabarits for discussion.
Utilisez l’une des moteurs de rendu de gabarits de formulaire intégrés ou implémentez le votre. Les moteurs de rendu personnalisés doivent implémenter une méthode render(nom_gabarit, context, request=None)
. Elle doit renvoyer un gabarit finalisé (sous forme de chaîne) ou générer TemplateDoesNotExist
.
-
class
BaseRenderer
¶ The base class for the built-in form renderers.
-
form_template_name
¶ - New in Django 4.1.
The default name of the template to use to render a form.
Defaults to
"django/forms/default.html"
, which is a proxy for"django/forms/table.html"
.Obsolète depuis la version 4.1.
The
"django/forms/default.html"
template is deprecated and will be removed in Django 5.0. The default will become"django/forms/div.html"
at that time.
-
formset_template_name
¶ - New in Django 4.1.
The default name of the template to use to render a formset.
Defaults to
"django/forms/formsets/default.html"
, which is a proxy for"django/forms/formsets/table.html"
.Obsolète depuis la version 4.1.
The
"django/forms/formset/default.html"
template is deprecated and will be removed in Django 5.0. The default will become"django/forms/formset/div.html"
template.
-
get_template
(template_name)¶ Subclasses must implement this method with the appropriate template finding logic.
-
render
(template_name, context, request=None)¶ Renders the given template, or raises
TemplateDoesNotExist
.
-
Moteurs de rendu de gabarits de formulaire intégrés¶
DjangoTemplates
¶
-
class
DjangoTemplates
¶
Ce moteur de rendu utilise un moteur indépendant DjangoTemplates
(sans rapport avec ce que vous pourriez avoit configuré dans le réglage TEMPLATES
). Il charge les gabarits en regardant d’abord dans le répertoire des gabarits de formulaire intégrés dans django/forms/templates
, puis dans les répertoires de gabarits des applications installées en utilisant le chargeur app_directories
.
Si vous souhaitez produire des gabarits avec des personnalisations provenant de votre réglage TEMPLATES
, comme par exemple en exploitant des processeurs de contexte, utilisez le moteur de rendu TemplatesSetting
.
-
class
DjangoDivFormRenderer
¶
Subclass of DjangoTemplates
that specifies
form_template_name
and
formset_template_name
as "django/forms/div.html"
and
"django/forms/formset/div.html"
respectively.
This is a transitional renderer for opt-in to the new <div>
based
templates, which are the default from Django 5.0.
Apply this via the FORM_RENDERER
setting:
FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"
Once the <div>
templates are the default, this transitional renderer will
be deprecated, for removal in Django 6.0. The FORM_RENDERER
declaration can
be removed at that time.
Jinja2
¶
-
class
Jinja2
¶
Ce moteur de rendu est semblable au moteur DjangoTemplates
, sauf qu’il utilise le moteur Jinja2
. Les gabarits des composants intégrés se trouvent dans django/forms/jinja2
et les applications installées peuvent fournir des gabarits dans un répertoire jinja2
.
Pour utiliser ce moteur, tous les formulaires et composants de votre projet et ses applications tierces doivent posséder des gabarits Jinja2. Si vous ne fournissez pas vous-même des gabarits pour les composants qui n’ont en pas, vous ne pouvez pas utiliser ce moteur de rendu. Par exemple, django.contrib.admin
ne contient pas de gabarits Jinja2 pour ses composants car ceux-ci font usage des balises de gabarits Django.
-
class
Jinja2DivFormRenderer
¶
A transitional renderer as per DjangoDivFormRenderer
above, but
subclassing Jinja2
for use with the Jinja2 backend.
Apply this via the FORM_RENDERER
setting:
FORM_RENDERER = "django.forms.renderers.Jinja2DivFormRenderer"
TemplatesSetting
¶
-
class
TemplatesSetting
¶
Ce moteur de rendu donne un contrôle complet sur la façon dont les gabarits de formulaires et de composants sont traités. Il utilise get_template()
pour trouver les gabarits sur la base de ce qui est configuré dans le réglage TEMPLATES
.
L’emploi de ce moteur de rendu en même temps que les gabarits intégrés nécessite l’une des deux conditions suivantes :
'django.forms'
se trouve dansINSTALLED_APPS
et au moins un moteur avecAPP_DIRS=True
.Le répertoire des gabarits intégrés doit figurer dans le réglage
DIRS
d’au moins un des moteurs de gabarits. Pour générer ce cheminimport django django.__path__[0] + '/forms/templates' # or '/forms/jinja2'
L’emploi de ce moteur de rendu nécessite que les gabarits de formulaires dont le projet a besoin puissent être localisés.
Contexte disponible dans les gabarits des jeux de formulaires¶
Les gabarits des jeux de formulaires reçoivent un contexte de BaseFormSet.get_context()
. Par défaut, les jeux de formulaires reçoivent un dictionnaire avec les valeurs suivantes :
formset
: l’instance du jeu de formulaires.
Contexte disponible dans les gabarits des formulaires¶
Les gabarits des formulaires reçoivent un contexte de Form.get_context()
. Par défaut, les formulaires reçoivent un dictionnaire avec les valeurs suivantes :
form
: le formulaire lié.fields
: tous les champs liés, exceptés les champs cachés.hidden_fields
: tous les champs liés cachés.errors
: toutes les erreurs de formulaire non liées aux champs ou liées à des champs cachés.
Contexte disponible dans les gabarits de composants¶
Les gabarits de composants reçoivent un contexte provenant de Widget.get_context()
. Par défaut, les composants reçoivent une seule valeur dans le contexte, widget
. Il s’agit d’un dictionnaire qui contient des valeurs comme :
name
valeur
attrs
is_hidden
template_name
Certains composants ajoutent d’autres informations dans le contexte. Par exemple, tous les composants héritant de Input
définissent widget['type']
et MultiWidget
définit widget['subwidgets']
donnant la possibilité de faire des boucles.
Redéfinition des gabarits de jeux de formulaires intégrés¶
Pour surcharger les gabarits des jeux de formulaires, vous devez utiliser le moteur de rendu TemplatesSetting
. Puis, le remplacement des gabarits de composants fonctionne de la même manière que le remplacement de n’importe quel autre gabarit d’un projet.
Redéfinition des gabarits de formulaires intégrés¶
Pour surcharger les gabarits des formulaires, vous devez utiliser le moteur de rendu TemplatesSetting
. Puis, le remplacement des gabarits de composants fonctionne de la même manière que le remplacement de n’importe quel autre gabarit d’un projet.
Redéfinition des gabarits des composants intégrés¶
Chaque composant possède un attribut template_name
avec une valeur telle que input.html
. Les gabarits des composants livrés avec Django sont stockés dans le chemin django/forms/widgets
. Par exemple, vous pouvez fournir un gabarit personnalisé pour input.html
en créant django/forms/widgets/input.html
. Voir Composants intégrés pour connaître le nom du gabarit de chaque composant.
Pour surcharger les gabarits de composants, vous devez utiliser le moteur de rendu TemplatesSetting
. Puis, le remplacement des gabarits de composants fonctionne de la même manière que le remplacement de n’importe quel autre gabarit d’un projet.