Ajout de styles aux instances de composants¶

Si vous souhaitez qu’une instance de composant apparaisse différemment d’une autre instance, il sera nécessaire d’indiquer des attributs supplémentaires au moment où l’objet composant est instancié et qu’il est attribué à un champ de formulaire (ce qui n’empêche pas d’ajouter aussi certaines règles dans vos fichiers CSS).

Par exemple, en prenant l’exemple de ce formulaire

from django import forms


class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField()

Ce formulaire inclut trois composants TextInput par défaut, avec le rendu HTML par défaut – pas de classe CSS, pas d’attribut supplémentaire. Cela signifie que les zones de saisie présentées par chaque composant seront affichées exactement de la même manière :

>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

Sur une page web réelle, il est souvent souhaitable d’afficher les composants de manière différente. Le champ commentaire pourrait nécessiter une plus grande zone de saisie, et le composant « name » pourrait être complété par une classe CSS spécifique. Il est aussi possible de définir l’attribut « type » pour profiter des nouveaux types de composants HTML5. Pour cela, utilisez le paramètre Widget.attrs lors de la création du composant :

class CommentForm(forms.Form):
    name = forms.CharField(widget=forms.TextInput(attrs={"class": "special"}))
    url = forms.URLField()
    comment = forms.CharField(widget=forms.TextInput(attrs={"size": "40"}))

Vous pouvez aussi modifier un composant dans la définition du formulaire

class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField()

    name.widget.attrs.update({"class": "special"})
    comment.widget.attrs.update(size="40")

Ou si le champ n’est pas directement déclaré dans le formulaire (comme pour les champs de formulaires de modèles), vous pouvez utiliser l’attribut Form.fields:

class CommentForm(forms.ModelForm):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields["name"].widget.attrs.update({"class": "special"})
        self.fields["comment"].widget.attrs.update(size="40")

Django se chargera ensuite d’inclure les attributs supplémentaires dans le résultat affiché :

>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" class="special" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" size="40" required></td></tr>

Vous pouvez également définir l’attribut HTML id à l’aide de attrs. Voir BoundField.id_for_label pour un exemple.

Ajout de styles aux classes de composants¶

Avec les composants, il est possible d’adjoindre des ressources (css et javascript) et de personnaliser plus encore leur apparence et leur comportement.

Rapidement dit, il est nécessaire de créer une sous-classe du composant et de soit définir une classe internet « Media » ou de créer une propriété « media ».

Ces méthodes impliquent une utilisation relativement avancée de la programmation Python et sont décrites en détails dans le guide thématique des fichiers annexes de formulaires.

Widget¶

class Widget(attrs=None)¶

Cette classe abstraite ne peut pas être affichée telle quelle, mais elle fournit l’attribut de base attrs. Vous pouvez aussi implémenter ou surcharger la méthode render() dans des composants personnalisés.

attrs¶

Un dictionnaire contenant les attributs HTML à définir pour le composant affiché.

>>> from django import forms
>>> name = forms.TextInput(attrs={"size": 10, "title": "Your name"})
>>> name.render("name", "A name")
'<input title="Your name" type="text" name="name" value="A name" size="10">'

Si vous attribuez une valeur True ou False à un attribut, il sera généré comme un attribut HTML5 booléen :

>>> name = forms.TextInput(attrs={"required": True})
>>> name.render("name", "A name")
'<input name="name" type="text" value="A name" required>'
>>>
>>> name = forms.TextInput(attrs={"required": False})
>>> name.render("name", "A name")
'<input name="name" type="text" value="A name">'

supports_microseconds¶

Un attribut qui vaut True par défaut. Si la valeur est False, les microsecondes faisant partie des valeurs datetime et time sont mises à 0.

format_value(value)¶

Nettoie et renvoie une valeur à utiliser dans le gabarit du composant. value n’est pas certain de constituer une saisie valide, il faut donc que les implémentations des sous-classes programment défensivement.

get_context(name, value, attrs)¶

Renvoie un dictionnaire de valeurs à utiliser lors du rendu des gabarits de composants. Par défaut, le dictionnaire contient une seule clé, 'widget', qui représente le composant dans un dictionnaire contenant les clés suivantes :

• 'name': le nom du champ en fonction du paramètre name.
• 'is_hidden': une valeur booléenne indiquant si ce composant est masqué.
• 'required': une valeur booléenne indiquant si le champ de ce composant est obligatoire.
• 'value': la valeur telle que renvoyée par format_value().
• 'attrs': les attributs HTML à définir sur le composant final. Combinaison de l’attribut attrs et du paramètre attrs.
• 'template_name': la valeur de self.template_name.

Les sous-classes de Widget peuvent fournir des valeurs de contexte personnalisées en surchargeant cette méthode.

id_for_label(id_)¶

Renvoie l’attribut HTML id de ce composant à l’usage de la balise <label>, en fonction de l’attribut id du champ. Renvoie une chaîne vide si id n’est pas disponible.

Ce point d’entrée est nécessaire car certains composants possèdent plusieurs éléments HTML et donc plusieurs id. Dans ce cas, cette méthode doit renvoyer une valeur id qui correspond au premier id dans les balises du composant.

render(name, value, attrs=None, renderer=None)¶

Produit un composant en HTML en utilisant le moteur de rendu donné. Si renderer vaut None, le moteur de rendu du réglage FORM_RENDERER est utilisé.

value_from_datadict(data, files, name)¶

Étant donné un dictionnaire de données et le nom de ce composant, renvoie la valeur du composant. files peut contenir des données provenant de request.FILES. Renvoie None si aucune valeur n’est disponible. Notez également que value_from_datadict peut être appelée plus d’une fois pendant le traitement des données de formulaire, ce qui signifie que si vous la personnalisez en ajoutant du traitement lourd, vous devriez implémenter vous-même un mécanisme de cache.

value_omitted_from_data(data, files, name)¶

Étant donné les dictionnaires data et files ainsi que le nom de ce composant, indique s’il existe des données ou des fichiers pour le composant.

Le résultat de cette méthode détermine si un champ d’un formulaire de modèle prend sa valeur par défaut.

Les composants CheckboxInput, CheckboxSelectMultiple et SelectMultiple sont des cas particuliers où la méthode renvoie toujours False car une case à cocher non cochée ou un <select multiple> sans sélection n’apparassent pas dans les données soumises par le formulaire HTML, ce qui fait qu’il est impossible de savoir si un utilisateur a saisi une valeur ou non.

use_fieldset¶

New in Django 4.1.

Un attribut pour savoir si le composant doit être contenu dans un <fieldset> avec une balise <legend> lorsqu’il est produit. Vaut False par défaut, mais True lorsque le composant contient plusieurs balises <input>, tels que pour les composants CheckboxSelectMultiple, RadioSelect, MultiWidget, SplitDateTimeWidget et SelectDateWidget.

use_required_attribute(initial)¶

Étant donné une valeur initial d’un champ de formulaire, renvoie si oui ou non le rendu du composant doit comporter l’attribut HTML required. Les formulaires utilisent cette méthode en compagnie de Field.required et de Form.use_required_attribute pour déterminer s’ils doivent afficher l’attribut required pour chacun de leurs champs.

Renvoie False par défaut pour les composants masqués, sinon True. Il y a des cas particuliers : FileInput et ClearableFileInput renvoient False lorsque initial est défini et CheckboxSelectMultiple renvoie toujours False car la validation des navigateurs exigerait que toutes les cases soient cochées au lieu de simplement une seule.

Surchargez cette méthode dans les composants personnalisés qui ne sont pas compatibles avec la validation des navigateurs. Par exemple, un composant d’édition de texte WSYSIWG s’appuyant sur un élément textarea masqué pourrait vouloir renvoyer toujours False pour éviter la validation du navigateur sur le champ masqué.

MultiWidget¶

class MultiWidget(widgets, attrs=None)¶

Un composant formé de plusieurs composants. MultiWidget fonctionne de concert avec le champ MultiValueField.

MultiWidget requiert un paramètre :

widgets¶

Un objet itérable contenant les composants nécessaires. Par exemple :

>>> from django.forms import MultiWidget, TextInput
>>> widget = MultiWidget(widgets=[TextInput, TextInput])
>>> widget.render("name", ["john", "paul"])
'<input type="text" name="name_0" value="john"><input type="text" name="name_1" value="paul">'

Vous pouvez fournir un dictionnaire afin d’indiquer des suffixes personnalisés pour l’attribut name de chaque sous-composant. Dans ce cas, pour chaque paire (clé, composant), la clé sera ajoutée au nom name du composant pour générer la valeur de l’attribut. Il est possible d’indiquer une seule clé avec une chaîne vide ('') pour demander la suppression du suffixe d’un des composants. Par exemple :

>>> widget = MultiWidget(widgets={"": TextInput, "last": TextInput})
>>> widget.render("name", ["john", "paul"])
'<input type="text" name="name" value="john"><input type="text" name="name_last" value="paul">'

Ainsi qu’une méthode obligatoire :

decompress(value)¶

Cette méthode accepte une seule valeur « compressée » à partir du champ et renvoie une liste de valeurs « décompressées ». La valeur d’entrée peut être considérée comme valide, mais pourrait être vide.

Cette méthode doit être implémentée par la sous-classe, et comme la valeur peut être vide, l’implémentation doit être défensive.

La logique de la « décompression » est qu’il est nécessaire de « scinder » la valeur combinée du champ de formulaire en valeurs distinctes pour chaque composant.

Un exemple pour illustrer ce processus est la façon dont SplitDateTimeWidget transforme une valeur datetime en une liste où la date et l’heure sont séparées :

from django.forms import MultiWidget


class SplitDateTimeWidget(MultiWidget):
    # ...

    def decompress(self, value):
        if value:
            return [value.date(), value.time()]
        return [None, None]

Astuce

Notez que MultiValueField possède une méthode complémentaire compress() qui joue le rôle inverse, combiner les valeurs nettoyées de tous les sous-composants en une seule valeur.

Il fournit un contenu de contexte spécifique :

get_context(name, value, attrs)¶

En plus de la clé 'widget' décrite dans Widget.get_context(), MultiWidget ajoute une clé widget['subwidgets'].

Il est possible d’effectuer cette boucle dans le gabarit du composant :

{% for subwidget in widget.subwidgets %}
    {% include subwidget.template_name with widget=subwidget %}
{% endfor %}

Voici un exemple de composant héritant de MultiWidget qui affiche une date avec le jour, le mois et l’année dans des listes déroulantes différentes. Ce composant est prévu pour être utilisé avec un champ DateField plutôt qu’avec un MultiValueField, c’est pourquoi nous avons implémenté value_from_datadict():

from datetime import date
from django import forms


class DateSelectorWidget(forms.MultiWidget):
    def __init__(self, attrs=None):
        days = [(day, day) for day in range(1, 32)]
        months = [(month, month) for month in range(1, 13)]
        years = [(year, year) for year in [2018, 2019, 2020]]
        widgets = [
            forms.Select(attrs=attrs, choices=days),
            forms.Select(attrs=attrs, choices=months),
            forms.Select(attrs=attrs, choices=years),
        ]
        super().__init__(widgets, attrs)

    def decompress(self, value):
        if isinstance(value, date):
            return [value.day, value.month, value.year]
        elif isinstance(value, str):
            year, month, day = value.split("-")
            return [day, month, year]
        return [None, None, None]

    def value_from_datadict(self, data, files, name):
        day, month, year = super().value_from_datadict(data, files, name)
        # DateField expects a single string that it can parse into a date.
        return "{}-{}-{}".format(year, month, day)

Le constructeur crée plusieurs composants Select dans une liste. La méthode super() utilise cette liste pour configurer le composant.

La méthode obligatoire decompress() partage une valeur datetime.date en valeurs distinctes de jour, mois et année correspondant à chaque composant. Si une date non valable a été choisie, comme par exemple un 30 février, DateField passe alors une chaîne à cette méthode qui doit l’analyser. Le return final gère le cas de la valeur None, qui signifie que nous n’avons aucune valeur par défaut pour nos sous-composants.

Lîmplémentation par défaut de value_from_datadict() renvoie une liste de valeurs correspondant à chaque Widget. C’est le comportement correct lorsqu’un composant MultiWidget est utilisé de concert avec un champ MultiValueField. Mais comme nous voulons utiliser ce composant avec un champ DateField, qui n’accepte qu’une seule valeur, nous avons surchargé cette méthode. L’implémentation ici combine les données des sous-composants en une chaîne mise en forme selon l’attente de DateField.

Composants chargés de la saisie de texte¶

Ces composants font usage des éléments HTML input et textarea.

Composants cases à cocher et listes à choix¶

Ces composants font usage des éléments HTML <select>, <input type='checkbox'> et <input type='radio'>.

Les composants qui produisent plusieurs options de choix possèdent un attribut option_template_name qui indique le gabarit à utiliser pour produire chaque choix. Par exemple, pour le composant Select, select_option.html produit une <option> dans un <select>.

Composants d’envoi de fichier¶

Composants multiples¶