Tutoriel Django - 6e partie : Vues génériques pour les listes et les détails

Cette traduction est incomplète. Aidez-nous à traduire cet article depuis l’anglais

Ce tutoriel améliore notre site web LocalLibrary, en ajoutant des pages de listes et de détails pour les livres et les auteurs. Ici nous allons apprendre les vues génériques basées sur des classes, et montrer comment elles peuvent réduire le volume de code à écrire pour les cas ordinaires. Nous allons aussi entrer plus en détail dans la gestion des URLs, en montrant comment réaliser des recherches de patterns simples.
Prérequis:

Avoir terminé tous les tutoriels précédents, y compris Django Tutorial Part 5: Creating our home page.

Objectif:

Comprendre où et comment utiliser des vues génériques basées sur classes, et comment extraire des patterns dans des URLs pour transmettre les informations aux vues.

Aperçu

Dans ce tutoriel, nous allons terminer la première version du site web LocalLibrary, en ajoutant des pages de listes et de détails pour les livres et les auteurs (ou pour être plus précis, nous allons vous montrer comment implémenter les pages concernant les livres, et vous faire créer vous-mêmes les pages concernant les auteurs !).

Le processus est semblable à celui utilisé pour créer la page d'index, processus que nous avons montré dans le tutoriel précédent. Nous allons avoir de nouveau besoin de créer des mappages d'URLs, des vues et des templates. La principale différence est que, pour la page des détails, nous allons avoir le défi supplémentaire d'extraire de l'URL des informations que nous transmettrons à la vue. Pour ces pages, nous allons montrer comment utiliser un type de vue complètement différent : des vues "listes" et "détails" génériques et basées sur des classes. Cela peut réduire significativement la somme de code nécessaire, les rendant ainsi faciles à écrire et à maintenir.

La partie finale de ce tutoriel montrera comment paginer vos données quand vous utilisez des vues "listes" génériques basées sur des classes.

Book list page

La page de liste des livres va afficher une liste de tous les enregistrements de livres disponibles, en utilisant l'URL: catalog/books/. La page va afficher le titre et l'auteur pour chaque enregistrement, et le titre sera un hyperlien vers la page de détails associée. La page aura la même structure et la même zone de navigation que les autres pages du site, et nous pouvons dès lors étendre le template de base (base_generic.html) que nous avons créé dans le tutoriel précédent.

Mappage d'URL

Ouvrez le fichier /catalog/urls.py, et copiez-y la ligne en gras ci-dessous. Comme pour la page d'index, cette fonction path() définit un pattern destiné à identifier l'URL ('books/'), une fonction vue qui sera appelée si l'URL correspond (views.BookListView.as_view()), et un nom pour ce mappage particulier.

urlpatterns = [
    path('', views.index, name='index'),
    path('books/', views.BookListView.as_view(), name='books'),
]

Comme discuté dans le tutoriel précédent, l'URL doit auparavant avoir identifié la chaîne /catalog, aussi la vue ne sera réellement appelée que pour l'URL complète: /catalog/books/.

La fonction vue a un format différent de celui que nous avions jusqu'ici : c'est parce que cette vue sera en réalité implémentée sous forme de classe. Nous allons la faire hériter d'une fonction vue générique existante, qui fait la plus grande partie de ce que nous souhaitons réaliser avec cette vue, plutôt que d'écrire notre propre fonction à partir de zéro.

En Django, on accède à la fonction appropriée d'une vue basée sur classe en appelant sa méthode de classe as_view(). Cela a pour effet de créer une instance de la classe, et de s'assurer que les bonnes méthodes seront appelées lors de requêtes HTTP.

Vue (basée sur classe)

Nous pourrions assez aisément écrire la vue "liste de livres" comme une fonction ordinaire (comme notre précédente vue "index"), qui interrogerait la base de données pour tous les livres, et qui ensuite appellerait render() pour passer la liste à un template spécifique. À la place, cependant, nous allons utiliser une vue "liste" générique, basée sur une classe (ListView), une classe qui hérite d'une vue existante. Parce que la vue générique implémente déjà la plupart des fonctionnalités dont nous avons besoin et suit les meilleures pratiques Django, nous pourrons créer une vue "liste" plus robuste avec moins de code, moins de répétition, et au final moins de maintenance.

Ouvrez le fichier catalog/views.py, et copiez-y le code suivant à la fin :

from django.views import generic

class BookListView(generic.ListView):
    model = Book

C'est tout ! La vue générique va adresser une requête à la base de données pour obtenir tous les enregistrements du modèle spécifié (Book), et ensuite rendre un template situé à l'adresse /locallibrary/catalog/templates/catalog/book_list.html (que nous allons créer ci-dessous). À l'intérieur du template vous pouvez accéder à la liste de livres grâce à la variable de template appelée object_list OU book_list (c'est-à-dire l'appellation générique "the_model_name_list").

Note : Ce chemin étrange vers le lieu du template n'est pas une faute de frappe : les vues génériques cherchent les templates dans /application_name/the_model_name_list.html (catalog/book_list.html dans ce cas) à l'intérieur du répertoire /application_name/templates/ (/catalog/templates/).

Vous pouvez ajouter des attributs pour changer le comportement par défaut utilisé ci-dessus. Par exemple, vous pouvez spécifier un autre fichier de template si vous souhaitez avoir plusieurs vues qui utilisent ce même modèle, ou bien vous pourriez vouloir utiliser un autre nom de variable de template, si book_list n'est pas intuitif par rapport à l'usage que vous faites de vos templates. Probablement, le changement le plus utile est de changer/filtrer le sous-ensemble des résultats retournés : au lieu de lister tous les livres, vous pourriez lister les 5 premiers livres lus par d'autres utilisateurs.

class BookListView(generic.ListView):
    model = Book
    context_object_name = 'my_book_list'   # your own name for the list as a template variable
    queryset = Book.objects.filter(title__icontains='war')[:5] # Get 5 books containing the title war
    template_name = 'books/my_arbitrary_template_name_list.html'  # Specify your own template name/location

Ré-écrire des méthodes dans des vues basées sur classes

Bien que nous n'ayons pas besoin de le faire ici, sachez qu'il vous est possible de ré-écrire des méthodes de classe.

Par exemple, nous pouvons ré-écrire la méthode get_queryset() pour changer la liste des enregistrements retournés. Cette façon de faire est plus flexible que simplement définir l'attribut queryset, comme nous l'avons fait dans le précédent fragment de code (bien qu'il n'y ait pas vraiment d'intérêt dans ce cas) :

class BookListView(generic.ListView):
    model = Book

    def get_queryset(self):
        return Book.objects.filter(title__icontains='war')[:5] # Get 5 books containing the title war

Nous pourrions aussi réécrire get_context_data(), afin d'envoyer au template des variables de contexte supplémentaires (par défaut c'est la liste de livres qui est envoyée). Le bout de code ci-dessous montre comment ajouter une variable appelée "some_data" au contexte (elle sera alors accessible comme variable de template).

class BookListView(generic.ListView):
    model = Book

    def get_context_data(self, **kwargs):
        # Call the base implementation first to get the context
        context = super(BookListView, self).get_context_data(**kwargs)
        # Create any data and add it to the context
        context['some_data'] = 'This is just some data'
        return context

Quand vous faites cela, il est important de suivre la procédure indiquée ci-dessus :

  • D'abord récupérer auprès de la superclasse le contexte existant.
  • Ensuite ajouter la nouvelle information de contexte.
  • Enfin retourner le nouveau contexte (mis à jour).

Note : Voyez dans Built-in class-based generic views (doc de Django) pour avoir beaucoup plus d'exemples de ce que vous pouvez faire.

Créer le template pour la Vue Liste

Créez le fichier HTML /locallibrary/catalog/templates/catalog/book_list.html, et copiez-y le texte ci-dessous. Comme nous l'avons dit ci-dessus, c'est ce fichier que va chercher par défaut la classe générique "liste" basée sur une vue (dans le cas d'un modèle appelé Book, dans une application appelée catalog).

Les templates pour vues génériques sont exactement comme les autres templates (cependant, bien sûr, le contexte et les informations envoyées au templates peuvent être différents). Comme pour notre template index, nous étendons notre template de base à la première ligne, et remplaçons ensuite le bloc appelé content.

{% extends "base_generic.html" %}

{% block content %}
  <h1>Book List</h1>
  {% if book_list %}
  <ul>
    {% for book in book_list %}
      <li>
        <a href="{{ book.get_absolute_url }}">{{ book.title }}</a> ({{book.author}})
      </li>
    {% endfor %}
  </ul>
  {% else %}
    <p>There are no books in the library.</p>
  {% endif %}       
{% endblock %}

La vue envoie le contexte (liste de livres), en utilisant par défaut les alias object_list et book_list ; l'un et l'autre fonctionnent.

Exécution conditionnelle

Nous utilisons les balises de templates if, else, et endif pour vérifier que la book_list a été définie et n'est pas vide. Si book_list est vide, alors la condition else affiche un texte expliquant qu'il n'y a pas de livres à lister. Si book_list n'est pas vide, nous parcourons la liste de livres.

{% if book_list %}
  <!-- code here to list the books -->
{% else %}
  <p>There are no books in the library.</p>
{% endif %}

La condition ci-dessus ne vérifie qu'un seul cas, mais vous pouvez ajouter d'autres tests grâce à la balise de template elif (par exemple {% elif var2 %}). Pour plus d'information sur les opérateurs conditionnels, voyez ici :  if, ifequal/ifnotequal, et ifchanged dans Built-in template tags and filters (Django Docs).

Boucles for

Le template utilise les balises de template for et endfor pour boucler à travers la liste de livres, comme montré ci-dessous. Chaque itération peuple la variable de template book avec l'information concernant l'élément courant de la liste.

{% for book in book_list %}
  <li> <!-- code here get information from each book item --> </li>
{% endfor %}

Bien que nous ne l'utilisions pas ici, Django, à l'intérieur de la boucle, va aussi créer d'autres variables que vous pouvez utiliser pour suivre l'itération. Par exemple, vous pouvez tester la variable forloop.last pour réaliser une action conditionnelle au dernier passage de la boucle.

Accéder aux variables

Le code à l'intérieur de la boucle crée un élément de liste pour chaque livre, élément qui montre à la fois le titre (comme lien vers la vue détail, encore à créer), et l'auteur.

<a href="{{ book.get_absolute_url }}">{{ book.title }}</a> ({{book.author}})

Nous accédont aux champs de l'enregistrement "livre" associé, en utilisant la notation "à points" (par exemple book.title et book.author), où le texte suivant l'item book est le nom du champ (comme défini dans le modèle).

Nous pouvons aussi appeler des fonctions contenues dans le modèle depuis l'intérieur de notre template — dans ce cas nous appelons Book.get_absolute_url() pour obtenir une URL que vous pouvez utiliser pour afficher dans la vue détail l'enregistrement associé. Cela fonctionne, pourvu que la fonction ne comporte pas d'arguments (il n'y a aucun moyen de passer des arguments !).

Note : Il nous faut être quelque peu attentif aux "effets de bord" quand nous appelons des fonctions dans nos templates. Ici nous récupérons simplement une URL à afficher, mais une fonction peut faire à peu près n'importe quoi — nous ne voudrions pas effacer notre base de données (par exemple) juste parce que nous avons affiché notre template !

Mettre à jour le template de base

Ouvrez le template de base (/locallibrary/catalog/templates/base_generic.html) et insérez {% url 'books' %} dans le lien URL pour All books, comme indiqué ci-dessous. Cela va afficher le lien dans toutes les pages (nous pouvons mettre en place ce lien avec succès, maintenant que nous avons créé le mappage d'URL "books").

<li><a href="{% url 'index' %}">Home</a></li>
<li><a href="{% url 'books' %}">All books</a></li>
<li><a href="">All authors</a></li>

À quoi cela ressemble-t-il ?

Vous ne pouvez pas encore construire la liste des livres, car il nous manque toujours une dépendance, à savoir le mappage d'URL pour la page de détail de chaque livre, qui est requise pour créer des hyperliens vers chaque livre. Nous allons montrer les vues liste et détail après la prochaine section.

Page de détail d'un livre

La page de détail d'un livre va afficher les informations sur un livre précis, auquel on accède en utilisant l'URL catalog/book/<id> (où <id> est la clé primaire pour le livre). En plus des champs définis dans le modèle Book (auteur, résumé, ISBN, langue et genre), nous allons aussi lister les détails des copies disponibles (BookInstances), incluant le statut, la date de retour prévue, la marque d'éditeur et l'id. Cela permettra à nos lecteurs, non seulement de s'informer sur le livre, mais aussi de confirmer si et quand il sera disponible.

Mappage d'URL

Ouvrez /catalog/urls.py et ajoutez-y le mappeur d'URL 'book-detail' indiqué en gras ci-dessous. Cette fonction path() définit un pattern, la vue générique basée sur classe qui lui est associée, ainsi qu'un nom.

urlpatterns = [
    path('', views.index, name='index'),
    path('books/', views.BookListView.as_view(), name='books'),
    path('book/<int:pk>', views.BookDetailView.as_view(), name='book-detail'),
]

Pour le chemin book-detail, le pattern d'URL utilise une syntaxe spéciale pour capturer l'id exact du livre que nous voulons voir. La syntaxe est très simple : les chevrons ('<' et '>') définissent la partie de l'URL qui doit être capturée et encadrent le nom de la variable que la vue pourra utiliser pour accéder aux données capturées. Par exemple, <something>  va capturer le pattern marqué et passer la valeur à la vue en tant que variable "something". De manière optionnelle, vous pouvez faire précéder le nom de variable d'une spécification de convertisseur, qui définit le type de la donnée (int, str, slug, uuid, path).

Dans ce cas, nous utilisons '<int:pk>' pour capturer l'id du livre, qui doit être une chaîne formatée d'une certaine manière, et passer cet id à la vue en tant que paramètre nommé pk (abbréviation pour primary key - clé primaire). C'est l'id qui doit être utilisé pour stocker le livre de manière unique dans la base de données, comme défini dans le modèle Book.

Note : Comme nous l'avons dit précédemment, notre URL correcte est en réalité catalog/book/<digits> (comme nous sommes dans l'application catalog/catalog/ est supposé).

Important : La vue générique basée sur classe "détail" s'attend à recevoir un paramètre appelé pk. Si vous écrivez votre propre fonction, vous pouvez utiliser le nom que vous voulez pour votre paramètre, ou même passer l'information avec un argument non nommé.

Introduction aux chemins et expressions régulières avancés

Note : Vous n'aurez pas besoin de cette section pour achever le tutoriel ! Nous en parlons parce que nous savons que cette option vous sera probablement utile dans votre avenir centré sur Django.

La recherche de pattern fournie par path() est simple et utile pour les cas (très communs) où vous voulez seulement capturer n'importe quelle chaîne ou entier. Si vous avez besoin d'un filtre plus affiné (par exemple pour filtrer seulement les chaînes qui ont un certain nombre de caractères), alors vous pouvez utiliser la méthode re_path().

Cette méthode est utilisée exactement comme path(), sauf qu'elle vous permet de spécifier un pattern utilisant une Expression régulière. Par exemple, le chemin précédent pourrait avoir été écrit ainsi :

re_path(r'^book/(?P<pk>\d+)$', views.BookDetailView.as_view(), name='book-detail'),

Les expressions régulières sont un outil de recherche de pattern extrêmement puissant. Ils sont, il est vrai, assez peu intuitifs et peuvent se révéler intimidants pour les débutants. Ci-dessous vous trouverez une introduction très courte !

La première chose à savoir est que les expressions régulières devraient ordinairement être déclarées en utilisant la syntaxe "chaîne littérale brute" (c'est-à-dire encadrées ainsi : r'<votre texte d'expression régulière va ici>').

L'essentiel de ce que vous aurez besoin de savoir pour déclarer une recherche de pattern est contenu dans le tableau qui suit :

Symbol Meaning
^ Recherche le début du texte.
$ Recherche la fin du texte.
\d Recherche un digit (0, 1, 2, ... 9).
\w Recherche un caractère de mot, c'est-à-dire tout caractère dans l'alphabet (majuscule ou minuscule), un digit ou un underscore (_).
+ Recherche au moins une occurence du caractère précédent. Par exemple, pour rechercher au moins 1 digit, vous utiliseriez \d+. Pour rechercher au moins 1 caractère "a", vous utiliseriez a+.
* Recherche zéro ou plus occurrence(s) du caractère précédent. Par exemple, pour rechercher "rien ou un mot", vous pourriez utiliser \w*.
( ) Capture la partie du pattern contenue dans les parenthèses. Toutes les valeurs capturées seront passées à la vue en tant que paramètres non nommés (si plusieurs patterns sont capturés, les paramètres associés seront fournis dans l'ordre de déclaration des captures).
(?P<name>...) Capture le pattern (indiqué par …) en tant que variable nommée (dans ce cas "name"). Les valeurs capturées sont passées à la vue avec le nom spécifié. Votre vue doit par conséquent déclarer un argument avec le même nom !
[  ] Recherche l'un des caractères contenus dans cet ensemble. Par exemple, [abc] va rechercher "a" ou "b" ou "c". [-\w] va rechercher le caractère "-" ou tout caractère de mot.

La plupart des autres caractères peuvent être pris littéralement.

Considérons quelques exemples réels de patterns :

Pattern Description
r'^book/(?P<pk>\d+)$'

C'est là l'expression régulière utilisée dans notre mappeur d'URL. Elle recherche une chaîne qui a book/ au commencement de la ligne (^book/), ensuite a au moins 1 digit (\d+), et enfin se termine (avec aucun caractère non-digit avant la fin du marqueur de ligne).

Elle capture aussi tous les digits (?P<pk>\d+) et les passe à la vue dans un paramètre appelé 'pk'. Les valeurs capturées sont toujours passées comme des chaînes !

Par exemple, cette expression régulière trouverait une correspondance dans l'URL book/1234, et enverrait alors une variable pk='1234' à la vue.

r'^book/(\d+)$'

Ceci rechercher la même URL que dans le cas précédent. L'information capturée serait envoyée à la vue en tant qu'argument non nommé.

r'^book/(?P<stub>[-\w]+)$'

Ceci recherche une chaîne qui a book/ au commencement de la ligne (^book/), ensuite a au moins 1 caractère étant soit un '-', soit un caractère de mot ([-\w]+), puis la fin. Ce pattern capture aussi cet ensemble de caractères et le passe à la vue en tant que paramètre nommé 'stub'.

Ceci est un pattern relativement typique pour un "stub". Les stubs sont des clés primaires basées sur des mots (plus agréables que des IDs) pour retrouver des données. Vous pouvez utiliser un stub si vous voulez que votre URL de livre contienne plus d'informations. Par exemple /catalog/book/the-secret-garden, plutôt que /catalog/book/33.

Vous pouvez capturer plusieurs patterns en une seule fois, et donc encoder beaucoup d'informations différentes dans l'URL.

Note : Comme défi, essayez d'envisager comment vous devriez encoder une URL pour lister tous les livres sortis en telle année, à tel mois et à tel jour, et l'expression régulière qu'il faudrait utiliser pour la rechercher.

Passer des options supplémentaires dans vos mappages d'URL

Une fonctionnalité que nous n'avons pas utilisée ici, mais que vous pourriez trouver valable, c'est que vous pouvez passer à la vue des options supplémentaires. Les options sont déclarées comme un dictionnaire que vous passez comme troisième argument (non nommé) à la fonction path(). Cette approche peut être utile si vous voulez utiliser la même vue pour des ressources multiples, et passer des données pour configurer son comportement dans chaque cas (ci-dessous nous fournissons un template différent dans chaque cas).

path('url/', views.my_reused_view, {'my_template_name': 'some_path'}, name='aurl'),
path('anotherurl/', views.my_reused_view, {'my_template_name': 'another_path'}, name='anotherurl'),

Note : Les options supplémentaires aussi bien que les patterns capturés sont passés à la vue comme arguments nommés. Si vous utilisez le même nom pour un pattern capturé et une option supplémentaire, alors seul la value du pattern capturé sera envoyé à la vue (la valeur spécifiée dans l'option supplémentaire sera abandonnée).

Vue (basée sur classe)

Ouvrez catalog/views.py, et copiez-y le code suivant à la fin du fichier :

class BookDetailView(generic.DetailView):
    model = Book

C'est tout ! La seule chose que vous avez à faire maintenant, c'est créer un template appelé /locallibrary/catalog/templates/catalog/book_detail.html, et la vue va lui passer les informations de la base de donnée concernant l'enregistrement Book spécifique, extrait par le mapper d'URL. À l'intérieur du template, vous pouvez accéder à la liste de livres via la variable de template appelée object OU book (c'est-à-dire, de manière générique, "le_nom_du_modèle").

Si vous en avez besoin, vous pouvez changer le template utilisé et le nom de l'objet-contexte utilisé pour désigner le livre dans le template. Vous pouvez aussi renommer les méthodes pour, par exemple, ajouter des informations supplémentaires au contexte.

Que se passe-t-il si l'enregistrement n'existe pas ?

Si l'enregistrement demandé n'existe pas, alors la vue générique basée sur classe "détail" va lever automatiquement pour vous une exception Http404 — en production, cela va automatiquement afficher une page appropriée "ressource non trouvée", que vous pouvez personnaliser si besoin.

Juste pour vous donner une idée de la manière dont tout cela fonctionne, le morceau de code ci-dessous montre comment vous implémenteriez cette vue comme une fonction si vous n'utilisiez pas la vue générique basée sur classe "détail".

def book_detail_view(request, primary_key):
    try:
        book = Book.objects.get(pk=primary_key)
    except Book.DoesNotExist:
        raise Http404('Book does not exist')
    
    return render(request, 'catalog/book_detail.html', context={'book': book})

La vue essaie d'abord d'obtenir du modèle l'enregistrement correspondant au livre spécifié. Si cela échoue, la vue devrait lever une exception Http404 pour indiquer que le livre est "non trouvé". L'étape finale est ensuite, comme d'habitude, d'appeler render() avec le nom du template et les données concernant le livre dans le paramètre context (comme un dictionnaire).

Une alternative consiste à utiliser la fonction get_object_or_404() comme un raccourci pour lever une exception Http404 si l'enregistrement n'existe pas.

from django.shortcuts import get_object_or_404

def book_detail_view(request, primary_key):
    book = get_object_or_404(Book, pk=primary_key)
    return render(request, 'catalog/book_detail.html', context={'book': book})

Créerle template de la Vue Détail

Créez le fichier HTML /locallibrary/catalog/templates/catalog/book_detail.html, et copiez-y le code ci-dessous. Comme on l'a dit plus haut, c'est là le nom de template attendu par défaut par la vue générique basée sur classe detail (pour un modèle appelé Book dans une application appelée catalog).

{% extends "base_generic.html" %}

{% block content %}
  <h1>Title: {{ book.title }}</h1>

  <p><strong>Author:</strong> <a href="">{{ book.author }}</a></p> <!-- author detail link not yet defined -->
  <p><strong>Summary:</strong> {{ book.summary }}</p>
  <p><strong>ISBN:</strong> {{ book.isbn }}</p> 
  <p><strong>Language:</strong> {{ book.language }}</p>  
  <p><strong>Genre:</strong> {{ book.genre.all|join:", " }}</p>  

  <div style="margin-left:20px;margin-top:20px">
    <h4>Copies</h4>

    {% for copy in book.bookinstance_set.all %}
      <hr>
      <p class="{% if copy.status == 'a' %}text-success{% elif copy.status == 'm' %}text-danger{% else %}text-warning{% endif %}">
        {{ copy.get_status_display }}
      </p>
      {% if copy.status != 'a' %}
        <p><strong>Due to be returned:</strong> {{ copy.due_back }}</p>
      {% endif %}
      <p><strong>Imprint:</strong> {{ copy.imprint }}</p>
      <p class="text-muted"><strong>Id:</strong> {{ copy.id }}</p>
    {% endfor %}
  </div>
{% endblock %}

Le lien vers l'auteur dans le template ci-dessus est vide, parce que nous n'avons pas encore crée de page détail pour un auteur. Une fois que cette page sera créée, vous pourrez remplacer l'URL par ceci :

<a href="{% url 'author-detail' book.author.pk %}">{{ book.author }}</a>

Bien qu'en un peu plus grand, presque tout ce qu'il y a dans ce template a été décrit précédemment :

  • Nous étendons notre template de base et récrivons le block "content".
  • Nous utilisons une procédure conditionnelle pour déterminer s'il faut ou non afficher tel contenu spécifique.
  • Nous utilisons une boucle for pour boucler sur des listes d'objets.
  • Nous accédons aux champs du contexte en utilisant la notation à point (parce que nous avons utilisé la vue générique detail, le contexte est nommé book ; nous pourrions aussi utiliser "object").

Une chose intéressante que nous n'avons pas encore vue, c'est la fonction book.bookinstance_set.all(). Cette méthode est "automagiquement" construite par Django pour retourner l'ensemble des enregistrements BookInstance associés à un Book particulier.

{% for copy in book.bookinstance_set.all %}
  <!-- code to iterate across each copy/instance of a book -->
{% endfor %}

Cette méthode est requise parce que vous déclarez un champ ForeignKey (one-to-many) seulement du côté "one" de la relation. Comme vous ne faites rien pour déclarer la relation dans les modèles opposés ("many"), Django n'a pas de champ pour récupérer l'ensemble des enregistrements associés. Pour remédier à ce problème, Django construit une fonction justement nommée "recherche inversée", que vous pouvez utiliser. Le nom de la fonction est construit en mettant en minuscule le nom du modèle où a été déclarée la ForeignKey, suivi de _set (ainsi la fonction créée dans Book est bookinstance_set()).

Note : Ici nous utilisons all() pour récupérer tous les enregistrements (comportement par défaut). Bien que vous puissiez utiliser la méthode filter() pour obtenir un sous-ensemble d'enregistrements dans le code, vous ne pouvez faire cela directement dans le template, parce que vous ne pouvez pas spécifier d'arguments dans les fonctions.

Prenez garde également que, si vous ne définissez pas un ordre (dans votre vue basée sur classe ou votre modèle), vous allez voir des erreurs de ce genre en provenance du serveur de développement :

[29/May/2017 18:37:53] "GET /catalog/books/?page=1 HTTP/1.1" 200 1637
/foo/local_library/venv/lib/python3.5/site-packages/django/views/generic/list.py:99: UnorderedObjectListWarning: Pagination may yield inconsistent results with an unordered object_list: <QuerySet [<Author: Ortiz, David>, <Author: H. McRaven, William>, <Author: Leigh, Melinda>]>
  allow_empty_first_page=allow_empty_first_page, **kwargs)

Ceci vient du fait que l'objet paginator s'attend à ce qu'un ORDER BY soit exécuté sur votre base de données sous-jacente. Sans cela il ne peut pas être sûr que les enregistrements retournés sont vraiment dans le bon ordre !

Ce tutoriel n'a pas (encore !) traité de la pagination, mais comme vous ne pouvez pas utiliser sort_by() et passer un paramètre (pour la même raison que le filter() décrit précédemment), vous avez le choix entre trois options :

  1. Ajouter un ordering lors de la déclaration de la class Meta dans votre modèle.
  2. Ajouter un attribut queryset dans votre vue personnalisée basée sur classe, en spécifiant un order_by().
  3. Ajouter une méthode get_queryset à votre vue personnalisée basée sur classe, et préciser de même un order_by().

Si vous décidez d'ajouter une class Meta au modèle Author (solution peut-être pas aussi flexible que personnalier la vue basée sur classe, mais assez facile), vous allez vous retrouver avec quelque chose de ce genre :

class Author(models.Model):
    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)
    date_of_birth = models.DateField(null=True, blank=True)
    date_of_death = models.DateField('Died', null=True, blank=True)

    def get_absolute_url(self):
        return reverse('author-detail', args=[str(self.id)])

    def __str__(self):
        return f'{self.last_name}, {self.first_name}'

    class Meta:
        ordering = ['last_name']

Bien sûr le champ n'est pas forcément last_name : ce pourrait être un autre champ.

Dernier point, mais non le moindre : vous devriez trier les données par un attribut/colonne qui a réellement un index (unique ou pas) dans votre base de données, afin d'éviter des problèmes de performance. Bien sûr ce n'est pas requis ici (ce serait un peu exagéré avec si peu de livres et d'utilisateurs), mais il vaut mieux avoir cela à l'esprit pour de futurs projets.

À quoi cela ressemble-t-il ?

À ce point, nous devrions avoir créé tout ce qu'il faut pour afficher à la fois la liste des livres et les pages de détail pour chaque livre. Lancez le serveur (python3 manage.py runserver) et ouvrez votre navigateur à l'adresse http://127.0.0.1:8000/.

Attention : Ne cliquez pas sur les liens vers le détail des auteurs : vous allez les créer lors du prochain défi !

Cliquez sur le lien Tous les livres pour afficher la liste des livres.

Book List Page

Ensuite cliquez sur un lien dirigeant vers l'un de vos livres. Si tout est réglé correctement, vous allez voir quelque chose de semblable à la capture d'écran suivante :

Book Detail Page

Pagination

If you've just got a few records, our book list page will look fine. However, as you get into the tens or hundreds of records the page will take progressively longer to load (and have far too much content to browse sensibly). The solution to this problem is to add pagination to your list views, reducing the number of items displayed on each page. 

Django has excellent inbuilt support for pagination. Even better, this is built into the generic class-based list views so you don't have to do very much to enable it!

Views

Open catalog/views.py, and add the paginate_by line shown in bold below.

class BookListView(generic.ListView):
    model = Book
    paginate_by = 10

With this addition, as soon as you have more than 10 records the view will start paginating the data it sends to the template. The different pages are accessed using GET parameters — to access page 2 you would use the URL /catalog/books/?page=2.

Templates

Now that the data is paginated, we need to add support to the template to scroll through the results set. Because we might want to do this in all list views, we'll do this in a way that can be added to the base template. 

Open /locallibrary/catalog/templates/base_generic.html and copy in the following pagination block below our content block (highlighted below in bold). The code first checks if pagination is enabled on the current page. If so then it adds next and previous links as appropriate (and the current page number). 

{% block content %}{% endblock %}
  
  {% block pagination %}
    {% if is_paginated %}
        <div class="pagination">
            <span class="page-links">
                {% if page_obj.has_previous %}
                    <a href="{{ request.path }}?page={{ page_obj.previous_page_number }}">previous</a>
                {% endif %}
                <span class="page-current">
                    Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}.
                </span>
                {% if page_obj.has_next %}
                    <a href="{{ request.path }}?page={{ page_obj.next_page_number }}">next</a>
                {% endif %}
            </span>
        </div>
    {% endif %}
  {% endblock %} 

The page_obj is a Paginator object that will exist if pagination is being used on the current page. It allows you to get all the information about the current page, previous pages, how many pages there are, etc. 

We use {{ request.path }} to get the current page URL for creating the pagination links. This is useful because it is independent of the object that we're paginating.

That's it!

What does it look like?

The screenshot below shows what the pagination looks like — if you haven't entered more than 10 titles into your database, then you can test it more easily by lowering the number specified in the paginate_by line in your catalog/views.py file. To get the below result we changed it to paginate_by = 2.

The pagination links are displayed on the bottom, with next/previous links being displayed depending on which page you're on.

Book List Page - paginated

Challenge yourself

The challenge in this article is to create the author detail and list views required to complete the project. These should be made available at the following URLs:

  • catalog/authors/ — The list of all authors.
  • catalog/author/<id> — The detail view for the specific author with a primary key field named <id>

The code required for the URL mappers and the views should be virtually identical to the Book list and detail views we created above. The templates will be different but will share similar behaviour.

Note:

  • Once you've created the URL mapper for the author list page you will also need to update the All authors link in the base template. Follow the same process as we did when we updated the All books link.
  • Once you've created the URL mapper for the author detail page, you should also update the book detail view template (/locallibrary/catalog/templates/catalog/book_detail.html) so that the author link points to your new author detail page (rather than being an empty URL). The line will change to add the template tag shown in bold below.
    <p><strong>Author:</strong> <a href="{% url 'author-detail' book.author.pk %}">{{ book.author }}</a></p> 
    

When you are finished, your pages should look something like the screenshots below.

Author List Page

Author Detail Page

Summary

Congratulations, our basic library functionality is now complete! 

In this article, we've learned how to use the generic class-based list and detail views and used them to create pages to view our books and authors. Along the way we've learned about pattern matching with regular expressions, and how you can pass data from URLs to your views. We've also learned a few more tricks for using templates. Last of all we've shown how to paginate list views so that our lists are manageable even when we have many records.

In our next articles, we'll extend this library to support user accounts, and thereby demonstrate user authentication, permissons, sessions, and forms.

See also

In this module