Le livre de

Faire des contextes de gabarit « sympathiques »

Vous avez peut être remarqué que l’exemple de gabarit de la liste « éditeur » stocke tous les livres dans une variable nommée object_list. Bien que cela fonctionne bien, tout n’est pas si « rose » pour les auteurs de gabarits : ils doivent « savoir » qu’ils ont ici affaire à des livres. Un meilleur nom pour cette variable pourrait être publisher_list ; le contenu de cette variable est évident.

Nous pouvons changer le nom de cette variable facilement avec l’argument template_object_name :

publisher_info = {
    "queryset" : Publisher.objects.all(),
    **"template_object_name" : "publisher",**
}

urlpatterns = patterns('',
    (r'^publishers/$', list_detail.object_list, publisher_info)
)

Fournir un template_object_name est toujours une bonne idée. Vos collègues qui écrivent des gabarits vous remercierons.

Ajouter un context supplémentaire

Souvent vous avez simplement besoin de présenter quelques informations supplémentaires à celles fournies par la vue générique. Par exemple, montrer une liste de tous les autres éditeurs sur chaque page détaillant un éditeur. La vue générique object_detail fournie l’éditeur au contexte, mais il semble qu’il ne soit pas possible d’obtenir la liste de tous les éditeurs dans ce gabarit.

C’est pourtant le cas : toutes les vues génériques acceptent un argument optionnel, extra_context. C’est un dictionnaire d’objets qui pourra être ajouté au contexte du gabarit. Ainsi, pour fournir la liste de tous les éditeurs sur la vue détail, nous utiliserons un dictionnaire info comme ceci :

publisher_info = {
    "queryset" : Publisher.objects.all(),
    "template_object_name" : "publisher",
    **"extra_context" : {"book_list" : Book.objects.all()}**
}

Ceci remplira une variable {{ book_list }} dans le contexte du gabarit. Ce patron peut être utilisé pour transmettre toute information vers le gabarit pour la vue générique. C’est très commode.

Cependant, il y a un bug subtil ici — pouvez vous le trouver ?

Le problème se présente lorsque les requêtes dans extra_context sont évaluées. Puisque cet exemple place Publisher.objects.all() dans l’URLconf, il sera évalué une seule fois (lorsque l’URLconf est chargé la première fois). Une fois que vous ajoutez ou retirez des éditeurs, vous noterez que la vue générique ne reflète pas ces changements jusqu’à ce vous rechargiez le serveur web (voir « Cache et QuerySet » dans l’annexe C pour plus d’information sur le moment où les Querysets sont mis en cache et évalués).

def get_books():
    return Book.objects.all()

publisher_info = {
    "queryset" : Publisher.objects.all(),
    "template_object_name" : "publisher",
    "extra_context" : **{"book_list" : get_books}**
}

publisher_info = {
    "queryset" : Publisher.objects.all(),
    "template_object_name" : "publisher",
    "extra_context" : **{"book_list" : Book.objects.all}**
}

Voir des sous-ensembles d’objets

Maintenant, intéressons nous à cette clef queryset que nous avons utilisé jusqu’à présent. La plupart des vues génériques prennent un des ces arguments queryset — C’est ainsi que la vue sait quel jeu d’objet il faut afficher (consultez « Selectionner des objets » au chapitre 5 pour une introduction aux QuerySets, et l’annexe C pour les détails complets).

Pour prendre un exemple simple, nous voudrions ordonner une liste de livres par date de publication, le plus récent en premier :

book_info = {
    "queryset" :
    Book.objects.all().order_by("-publication_date"),
}

urlpatterns = patterns('',
    (r'^publishers/$', list_detail.object_list, publisher_info),
    **(r'^books/$', list_detail.object_list, book_info),**
)

C’est un exemple relativement simple, mais il illustre bien l’idée. Bien sûr, vous voudrez généralement faire plus que simplement réordonner des objets. Si vous voulez présenter une liste des livres selon un éditeur particulier, vous pouvez utiliser la même technique :

**apress_books = {**
    **"queryset": Book.objects.filter(publisher__name="Apress
    Publishing"),**
    **"template_name" : "books/apress_list.html"**
**}**

urlpatterns = patterns('',
    (r'^publishers/$', list_detail.object_list, publisher_info),
    **(r'^books/apress/$', list_detail.object_list,
    apress_books),**
)

Remarquez que même avec un queryset filtré, nous utilisons aussi un nom de gabarit personnalisé. Dans le cas contraire, la vue générique utiliserait le même gabarit que la liste native des objets, ce qui pourrait ne pas être ce que nous voulons. Notez aussi que ce n’est pas une façon très élégante de faire des livres spécifiques à des éditeurs. Si nous voulons ajouter une nouvelle page éditeurs, nous aurons besoin d’une autre poignée de lignes dans l’URLconf, et cela ne serait pas raisonnable au delà de quelques éditeurs. Nous aborderons ce problème à la section suivante.

Filtrages complexes à l’aide de l’encapsulation de fonction

Un autre besoin courant est de filtrer les objets donnés dans une page liste, selon les clefs dans l’URL. Auparavant, nous avons codé le nom de l’éditeur dans l’URLconf, mais si nous avions voulu écrire une vue qui affiche tous les livres selon un éditeur arbitraire ? Nous pouvons envelopper la vue générique object_list pour éviter d’écrire beaucoup de code à la main. Comme d’habitude, nous commençerons par écrire un URLconf :

urlpatterns = patterns('',
    (r'^publishers/$', list_detail.object_list, publisher_info),
    **(r'^books/(w+)/$', books_by_publisher),**
)

Ensuite, nous écrirons la vue books_by_publisher elle même :

from django.http import Http404
from django.views.generic import list_detail
from mysite.books.models import Book, Publisher

def books_by_publisher(request, name):

    # Look up the publisher (and raise a 404 if it can't be
    found).
    try:
        publisher = Publisher.objects.get(name__iexact=name)
    except Publisher.DoesNotExist:
        raise Http404

    # Use the object_list view for the heavy lifting.
    return list_detail.object_list(
        request,
        queryset = Book.objects.filter(publisher=publisher),
        template_name = "books/books_by_publisher.html",
        template_object_name = "books",
        extra_context = {"publisher" : publisher}
    )

Ceci fonctionne parcequ’il n’y a vraiment rien de spécial au sujet des vues génériques — ce sont juste des fonctions Python ? Comme toute fonction de vue, les vues génériques attendent un certain jeu d’arguments et retournent des objets HttpResponse. Ainsi, il est incroyablement facile d’encapsuler une petite fonction autour d’une vue générique qui fait le travail supplémentaire avant (ou après ; voyez la prochaine section) et remet le résultat à la vue générique.

Faire des actions supplémentaires

Le dernier patron commun que nous verrons implique quelque travail supplémentaire avant ou après l’appel de la vue générique.

Imaginez que nous ayons un champ last_accessed pour l’objet Author que nous utilisions dans le but de garder la trace de la dernière fois où quelqu’un à consulté cet auteur. La vue générique object_detail, bien sur, ne saura rien de ce champs. Encore une fois, nous pouvons facilement écrire une vue personnalisée pour garder ce champs à jour.

Tout d’abord, nous devons ajouter quelques détails dans l’URLconf afin de pointer sur une vue personnalisée :

from mysite.books.views import author_detail

urlpatterns = patterns('',
    #...
    **(r'^authors/(?P<author_id>d+)/$', author_detail),**
)

Ensuite nous écrivons notre fonction enveloppe :

import datetime
from mysite.books.models import Author
from django.views.generic import list_detail
from django.shortcuts import get_object_or_404

def author_detail(request, author_id):
    # Look up the Author (and raise a 404 if she's not found)
    author = get_object_or_404(Author, pk=author_id)

    # Record the last accessed date
    author.last_accessed = datetime.datetime.now()
    author.save()

    # Show the detail page
    return list_detail.object_detail(
        request,
        queryset = Author.objects.all(),
        object_id = author_id,
    )

Nous pouvons utiliser une syntaxe similaire pour altérer la réponse retournée par la vue générique. Si nous voulons fournir une version texte téléchargeable de la liste des auteurs, nous pouvons utiliser une vue telle que :

def author_list_plaintext(request):
   response = list_detail.object_list(
       request,
       queryset = Author.objects.all(),
       mimetype = "text/plain",
       template_name = "books/author_list.txt"
   )
   response["Content-Disposition"] = "attachment;
   filename=authors.txt"
   return response

Ceci fonctionne parce que les vues génériques renvoient de simple objets HttpResponse qui peuvent être considérés comme des dictionnaires pour paramétrer les entêtes HTTP. Cette « disposition de contenu » , de ce fait, indique au navigateur de télécharger et de sauvegarder la page au lieu de l’afficher.