Générer un formulaire simple

Commençons par mettre à jour notre template de détail de sondage issu du dernier tutoriel de façon à ce que le template contienne un élement HTML <form>:

<h1>{{ poll.question }}</h1>

{% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}


<form action="/polls/{{ poll.id }}/vote/" method="post">
{% for choice in poll.choice_set.all %}
    <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" />

    <label for="choice{{ forloop.counter }}">{{ choice.choice }}</label><br />
{% endfor %}
<input type="submit" value="Voter" />
</form>

Un bref rappel :

• Le template ci-dessus affiche un bouton radio pour chaque choix du sondage. La valeur value de chaque bouton radio est associée à l'ID de chaque choix. Le nom name de chaque bouton radio est "choice". Cela signifie que lorsque quelqu'un sélectionne l'un des boutons radio et soumet le formulaire, il envoie la donnée de type POST choice=3. C'est un formulaire HTML 101.
• Nous avons assigné l'action du formulaire à /polls/{{ poll.id }}/vote/, et nous avons mis method="post". L'utilisation de method="post" (au contraire de method="get") est très importante, car le fait de soumettre ce formulaire va être à l'origine d'une modification des données du côté du serveur. À chaque fois que vous créez un formulaire qui modifie des données sur le serveur, utilisez method="post". Cet adage n'est pas spécifique à Django, ce sont juste de bonnes pratiques de développement web.

À présent, créons une vue Django qui récupère les données soumises et fait quelque chose avec. Rappelez-vous, dans le Tutoriel 3, nous avons créé une URLconf pour l'application de sondage qui incluait cette ligne:

(r'^(?P<poll_id>\d+)/vote/$', 'monsite.polls.views.vote'),

Donc créons une fonction vote() dans monsite/polls/views.py:

from django.shortcuts import get_object_or_404, render_to_response
from django.http import HttpResponseRedirect
from monsite.polls.models import Choice, Poll
# ...
def vote(request, poll_id):
    p = get_object_or_404(Poll, pk=poll_id)
    try:
        selected_choice = p.choice_set.get(pk=request.POST['choice'])
    except (KeyError, Choice.DoesNotExist):
        # Réaffiche le formulaire de vote.
        return render_to_response('polls/detail.html', {
            'poll': p,
            'error_message': "Vous n'avez pas sélectionné de choix.",
        })
    else:
        selected_choice.votes += 1
        selected_choice.save()
        # Retourne toujours un HttpResponseRedirect après validation
        # des données POST. Ceci empèche que les données soient postées
        # deux fois si l'utilisateur clique sur le bouton Précédent.
        return HttpResponseRedirect('/polls/%s/results/' % p.id)

Ce code inclus des parties que nous n'avons pas encore étudiées dans ce tutoriel :

• request.POST est un objet de type dictionnaire qui vous laisse accéder aux données soumises avec les mots-clé. Dans notre cas, request.POST['choice'] retourne l'ID du choix sélectionné, sous forme de chaîne de caractères. Les valeurs issues de request.POST sont toujours des chaînes de caractères.

  Notez que Django vous permet aussi d'accéder via request.GET aux données de type GET de la même façon -- mais nous utilisons explicitement request.POST dans notre code, pour nous assurer que la modification des données se fasse uniquement par un appel à POST.

• request.POST['choice'] déclenchera une KeyError si choice n'a pas été obtenu par des données de type POST. Le code ci-dessus vérifie les KeyError et réaffiche le formulaire de sondage avec un message d'erreur si choice n'a pas été donné.

• Après avoir incrémenté le compteur associé au choix soumis, le script retourne une HttpResponseRedirect à la place du HttpResponse habituel. HttpResponseRedirect prend un seul argument : l'URL vers laquelle l'utilisateur va être redirigé. Vous pouvez omettre de mentionner le « http:// » et le nom de domaine quand cela est possible. Cela permet à votre appli d'être portable sur différents domaines.

  Comme le commentaire Python le souligne, vous devez toujours retourner une HttpResponseRedirect après avoir traité une donnée de type POST avec succès. Cet adage n'est pas spécifique à Django, c'est juste une bonne pratique de développement web.

Comme il est mentionné dans le Tutoriel 3, request est un objet HTTPRequest. Pour en savoir plus au sujet des objets HTTPRequest, lisez la documentation sur les requêtes et réponses.

Après qu'un vote ait été effectué dans un sondage, la vue vote() redirige vers la page de résultats du sondage. Écrivons cette vue:

def results(request, poll_id):
    p = get_object_or_404(Poll, pk=poll_id)
    return render_to_response('polls/results.html', {'poll': p})

C'est presque la même que la vue detail() du Tutoriel 3. La seule différence est le nom du template. Nous nous occuperons de la redondance plus tard.

Maintenant, créons un template results.html:

<h1>{{ poll.question }}</h1>

<ul>
{% for choice in poll.choice_set.all %}
    <li>{{ choice.choice }} -- {{ choice.votes }} vote{{ choice.votes|pluralize }}</li>
{% endfor %}
</ul>

À présent, rendez vous à l'adresse /polls/1/ dans votre navigateur et soumettez un vote. Vous devriez voir une page de résultats qui est mise à jour à chacun de vos votes. Si vous soumettez le formulaire sans avoir spécifié de choix, vous devriez observer le message d'erreur.

Utilisez les vues génériques : Moins il y a de code mieux c'est

Les vues detail() (du Tutoriel 3) et results() sont ridiculeusement simples -- et, comme nous l'avons signalé plus haut, redondantes. La vue index() (du Tutoriel 3 aussi), qui affiche une liste de sondages, est similaire.

Ces vues correspondent à des cas courants de développement Web basic : récupérer des données de la base de données en fonction d'un paramètre passé dans l'URL, charger un template et retourner le template complété. Comme c'est si courant, Django dispose d'un raccourci, baptisé le système des « vues génériques ».

Les vues génériques fournissent une couche d'abstraction tellement importante que vous n'avez même pas besoin de rédiger du code Python pour écrire votre appli.

Convertissons notre application de sondage en utilisant le système des vues génériques, nous allons ainsi pouvoir supprimer une bonne partie du code que nous avons écrit précédemment. Il suffit de quelques étapes pour réaliser la conversion.

Premièrement, éditez votre fichier d'URLconf polls/urls.py. Il devrait ressembler à ça, d'après les tutoriaux précédents:

from django.conf.urls.defaults import *

urlpatterns = patterns('monsite.polls.views',
    (r'^$', 'index'),
    (r'^(?P<poll_id>\d+)/$', 'detail'),
    (r'^(?P<poll_id>\d+)/results/$', 'results'),
    (r'^(?P<poll_id>\d+)/vote/$', 'vote'),
)

Faites le ressembler à:

from django.conf.urls.defaults import *
from monsite.polls.models import Poll

info_dict = {
    'queryset': Poll.objects.all(),
}

urlpatterns = patterns('',
    (r'^$', 'django.views.generic.list_detail.object_list', info_dict),
    (r'^(?P<object_id>\d+)/$', 'django.views.generic.list_detail.object_detail', info_dict),
    (r'^(?P<object_id>\d+)/results/$', 'django.views.generic.list_detail.object_detail', dict(info_dict, template_name='polls/results.html')),
    (r'^(?P<poll_id>\d+)/vote/$', 'monsite.polls.views.vote'),
)

Nous utilisons ici deux vues génériques : object_list et object_detail. Respectivement, ces deux vues rendent abstraits les concepts « d'affichage d'une liste d'objets » et « d'affichage d'une page de détails pour un type particulier d'objet ».

• Chaque vue générique a besoin de connaître sur quelles données est-ce qu'elle va agir. Ces données sont fournies grâce à un dictionnaire. La clé queryset de ce dictionnaire pointe sur la liste d'objets qui doit être manipulée par la vue générique.
• La vue générique object_detail attend la valeur ID issue de l'URL qui doit être appelée "object_id", nous avons donc changé poll_id en object_id pour la vue générique.

Par défaut, la vue générique object_detail utilise un template appelé <nom_appli>/<nom_module>_detail.html. Dans notre cas, ce sera le template appelé "polls/poll_detail.html". Donc, renommons polls/detail.html en polls/poll_detail.html, et changeons la ligne render_to_response() en vote().

De façon similaire, la vue générique object_list utilise un template appelé <nom_appli>/<nom_module>_list.html. Donc, renommons polls/index.html en polls/poll_list.html.

Puisque nous avons plus d'une entrée dans l'URLconf qui utilisent object_detail pour l'application de sondage, nous spécifions manuellement un nom de template pour la vue des résultats : template_name='polls/results.html'. Sinon, les deux vues auraient utilisé le même template. Notez l'utilisation de dict() pour retourner un dictionnaire modifié à la place.

Dans les tutoriels précédents, les templates sont utilisés dans un contexte contenant les variables poll et latest_poll_list. Ici, les vues génériques nécessitent d'avoir les variables contextuelles object et object_list. Éditez vos templates et modifiez chaque référence à latest_poll_list par object_list, et chaque référence à poll par object.

Vous pouvez maintenant supprimer les vues index(), detail() et results() de polls/views.py. Nous n'en avons plus besoin -- elles ont été remplacées par les vues génériques.

La vue vote() est toujours requise. Néanmoins, elle doit être modifiée pour être utilisée dans les nouveaux templates et les nouvelles variables contextuelles. Changez l'appel au template polls/detail.html par polls/poll_detail.html, et passez object dans le contexte au lieu de poll.

Lancez le serveur et utilisez votre nouvelle appli de sondage avec les vues génériques.

Pour davantage de détails quant aux vues génériques, lisez la documentation sur les vues génériques.

À venir

Les tutoriels s'arrêtent ici pour le moment. Mais revenez prochainement pour la suite des réjouissances :

• Utilisation avancée des formulaires
• Utilisation du framework RSS
• Utilisation du framework de cache
• Utilisation du framework de commentaires
• Fonctionnalités avancées d'administration : Permissions
• Fonctionnalités avancées d'administration : Javascript

Vous pouvez maintenant retourner à la page d'accueil des traductions de la documentation de Django.

Cette traduction correspond à la révision 3589 (post 0.95).