--- title: "L’API du rendu des formulaires" version: 2.2 locale: fr source: https://docs.djangoproject.com/fr/2.2/ref/forms/renderers/ canonical: https://djangodocs.dev/fr/2.2/ref/forms/renderers/ --- # L’API du rendu des formulaires Les composants de formulaires de Django sont produits en utilisant le [système des moteurs de gabarit](/fr/2.2/topics/templates/) 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`](/fr/2.2/ref/settings/#std-setting-FORM_RENDERER). Par défaut, il contient `'`[`django.forms.renderers.DjangoTemplates`](#django.forms.renderers.DjangoTemplates)`'`. Il est aussi possible de définir un moteur de rendu personnalisé en définissant l’attribut [`Form.default_renderer`](/fr/2.2/ref/forms/api/#django.forms.Form.default_renderer) ou en utilisant le paramètre `renderer` de [`Widget.render()`](/fr/2.2/ref/forms/widgets/#django.forms.Widget.render). Utilisez l’une des [moteurs de rendu de gabarits de formulaire intégrés](#built-in-template-form-renderers) 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`](/fr/2.2/topics/templates/#django.template.TemplateDoesNotExist). ## Moteurs de rendu de gabarits de formulaire intégrés ### `DjangoTemplates` #### `class DjangoTemplates` Ce moteur de rendu utilise un moteur indépendant [`DjangoTemplates`](/fr/2.2/topics/templates/#django.template.backends.django.DjangoTemplates) (sans rapport avec ce que vous pourriez avoit configuré dans le réglage [`TEMPLATES`](/fr/2.2/ref/settings/#std-setting-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`](/fr/2.2/ref/templates/api/#django.template.loaders.app_directories.Loader). Si vous souhaitez produire des gabarits avec des personnalisations provenant de votre réglage [`TEMPLATES`](/fr/2.2/ref/settings/#std-setting-TEMPLATES), comme par exemple en exploitant des processeurs de contexte, utilisez le moteur de rendu [`TemplatesSetting`](#django.forms.renderers.TemplatesSetting). ### `Jinja2` #### `class Jinja2` Ce moteur de rendu est semblable au moteur [`DjangoTemplates`](#django.forms.renderers.DjangoTemplates), sauf qu’il utilise le moteur [`Jinja2`](/fr/2.2/topics/templates/#django.template.backends.jinja2.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 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`](/fr/2.2/ref/contrib/admin/#module-django.contrib.admin) ne contient pas de gabarits Jinja2 pour ses composants car ceux-ci font usage des balises de gabarits Django. ### `TemplatesSetting` #### `class TemplatesSetting` Ce moteur de rendu donne un contrôle complet sur la façon dont les gabarits de composants sont traités. Il utilise [`get_template()`](/fr/2.2/topics/templates/#django.template.loader.get_template) pour trouver les gabarits de composants sur la base de ce qui est configuré dans le réglage [`TEMPLATES`](/fr/2.2/ref/settings/#std-setting-TEMPLATES). L’emploi de ce moteur de rendu en même temps que les gabarits de composants intégrés nécessite l’une des deux conditions suivantes : - `'django.forms'` se trouve dans [`INSTALLED_APPS`](/fr/2.2/ref/settings/#std-setting-INSTALLED_APPS) et au moins un moteur avec [`APP_DIRS=True`](/fr/2.2/ref/settings/#std-setting-TEMPLATES-APP_DIRS). - Le répertoire des gabarits de composants intégrés doit figurer dans le réglage [`DIRS`](/fr/2.2/ref/settings/#std-setting-TEMPLATES-DIRS) d’au moins un des moteurs de gabarits. Pour générer ce chemin ``` import 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 de composants Les gabarits de composants reçoivent un contexte provenant de [`Widget.get_context()`](/fr/2.2/ref/forms/widgets/#django.forms.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`](/fr/2.2/ref/forms/widgets/#django.forms.MultiWidget) définit `widget['subwidgets']` donnant la possibilité de faire des boucles. ## 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](/fr/2.2/ref/forms/widgets/#built-in-widgets) pour connaître le nom du gabarit de chaque composant. Pour surcharger les gabarits de composants, vous devez utiliser le moteur de rendu [`TemplatesSetting`](#django.forms.renderers.TemplatesSetting). Puis, le remplacement des gabarits de composants fonctionne [de la même manière](/fr/2.2/howto/overriding-templates/) que le remplacement de n’importe quel autre gabarit d’un projet.