Working on the administration panel

source/part-1-workspace/django/_index.adoc

@@ -173,7 +173,7 @@ Dans l'immédiat, nous allons ajouter `django` dans une version strictement inf
 
 [source,bash]
 ----
-$ echo 'django<3.2' > requirements/base.txt
+$ echo 'django==3.2' > requirements/base.txt
 $ echo '-r base.txt' > requirements/prod.txt
 $ echo '-r base.txt' > requirements/dev.txt
 ----
@@ -327,7 +327,7 @@ La structure de vos répertoires devient celle-ci:
 
 ==== Fonctionement général
 
-Le métier de programmeur est devenu de plus en plus complexe. Il y a 20 ans, nous pouvions nous contenter d'une simple page PHP dans laquelle nous mixions l'ensemble des actios à réaliser: requêtes en bases de données, construction de la page, ... 
+Le métier de programmeur est devenu de plus en plus complexe. Il y a 20 ans, nous pouvions nous contenter d'une simple page PHP dans laquelle nous mixions l'ensemble des actios à réaliser: requêtes en bases de données, construction de la page, ...
 La recherche d'une solution a un problème n'était pas spécialement plus complexe - dans la mesure où le rendu des enregistrements en direct n'était finalement qu'une forme un chouia plus évoluée du `print()` ou des `System.out.println()` - mais c'était l'évolutivité des applications qui en prenait un coup: une grosse partie des tâches étaient dupliquées entre les différentes pages, et l'ajout d'une nouvelle fonctionnalité était relativement ardue.
 
 Django (et d'autres cadriciels) résolvent ce problème en se basant ouvertement sur le principe de `Don't repeat yourself` footnote:[DRY].
@@ -338,17 +338,17 @@ Le chemin parcouru par une requête est expliqué en (petits) détails ci-dessou
 .How it works
 image::images/diagrams/django-how-it-works.png[]
 
-*1. Un utilisateur ou un visiteur souhaite accéder à une URL hébergée et servie par notre application*. 
+*1. Un utilisateur ou un visiteur souhaite accéder à une URL hébergée et servie par notre application*.
 Ici, nous prenons l'exemple de l'URL fictive `https://gwift/wishes/91827`.
 Lorsque cette URL "arrive" dans notre application, son point d'entrée se trouvera au niveau des fichiers `asgi.py` ou `wsgi.py`. Nous verrons cette partie plus tard, et nous pouvons nous concentrer sur le chemin interne qu'elle va parcourir.
 
-*Etape 0* - La première étape consiste à vérifier que cette URL répond à un schéma que nous avons défini dans le fichier `gwift/urls.py`. 
+*Etape 0* - La première étape consiste à vérifier que cette URL répond à un schéma que nous avons défini dans le fichier `gwift/urls.py`.
 
 *Etape 1* - Si ce n'est pas le cas, l'application n'ira pas plus loin et retournera une erreur à l'utilisateur.
 
 
-*Etape 2* - Django va parcourir l'ensemble des _patterns_ présents dans le fichier `urls.py` et s'arrêtera sur le premier qui correspondra à la requête qu'il a reçue. 
-Ce cas est relativement trivial: la requête `/wishes/91827` a une correspondance au niveau de la ligne `path("wishes/<int:wish_id>` dans l'exemple ci-dessous. 
+*Etape 2* - Django va parcourir l'ensemble des _patterns_ présents dans le fichier `urls.py` et s'arrêtera sur le premier qui correspondra à la requête qu'il a reçue.
+Ce cas est relativement trivial: la requête `/wishes/91827` a une correspondance au niveau de la ligne `path("wishes/<int:wish_id>` dans l'exemple ci-dessous.
 Django va alors appeler la fonction footnote:[Qui ne sera pas toujours une fonction. Django s'attend à trouver un _callable_, c'est-à-dire n'importe quel élément qu'il peut appeler comme une fonction.] associée à ce _pattern_, c'est-à-dire `wish_details` du module `gwift.views`.
 
 [source,python]
@@ -367,7 +367,7 @@ urlpatterns = [
 <2> Champomy et cotillons! Nous avons une correspondance avec `wishes/details/91827`
 
 
-TODO: En fait, il faudrait quand même s'occuper du modèle ici. 
+TODO: En fait, il faudrait quand même s'occuper du modèle ici.
 TODO: et de la mise en place de l'administration, parce que nous en aurons besoin pour les étapes de déploiement.
 
 [line-through]#Nous n'allons pas nous occuper de l'accès à la base de données pour le moment (nous nous en occuperons dans un prochain chapitre) et nous nous contenterons de remplir un canevas avec un ensemble de données.#
@@ -485,7 +485,7 @@ plugins =
 
 === Structure finale de notre environnement
 
-Nous avons donc la strucutre finale pour notre environnement de travail:
+Nous avons donc la structure finale pour notre environnement de travail:
 
 [source,bash]
 ----
@@ -519,7 +519,7 @@ Nous avons donc la strucutre finale pour notre environnement de travail:
 
 === Cookie cutter
 
-Pfiou! Ca en fait des commandes et du boulot pour "juste" démarrer un nouveau projet, non? Sachant qu'en plus, nous avons dû modifier des fichiers, déplacer des dossiers, ajouter des dépendances, configurer une base de données, ... 
+Pfiou! Ca en fait des commandes et du boulot pour "juste" démarrer un nouveau projet, non? Sachant qu'en plus, nous avons dû modifier des fichiers, déplacer des dossiers, ajouter des dépendances, configurer une base de données, ...
 
 Bonne nouvelle! Il existe des générateurs, permettant de démarrer rapidement un nouveau projet sans (trop) se prendre la tête. Le plus connu (et le plus personnalisable) est https://cookiecutter.readthedocs.io/[Cookie-Cutter], qui se base sur des canevas _type https://pypi.org/project/Jinja2/[Jinja2]_, pour créer une arborescence de dossiers et fichiers conformes à votre manière de travailler. Et si vous avez la flemme de créer votre propre canevas, vous pouvez utiliser https://cookiecutter-django.readthedocs.io[ceux qui existent déjà].
 
@@ -542,10 +542,10 @@ Pour démarrer, créez un environnement virtuel (comme d'habitude):
  [SUCCESS]: Project initialized, keep up the good work!
 ----
 
-Si vous explorez les différents fichiers, vous trouverez beaucoup de similitudes avec la configuration que nous vous proposions ci-dessus. 
+Si vous explorez les différents fichiers, vous trouverez beaucoup de similitudes avec la configuration que nous vous proposions ci-dessus.
 En fonction de votre expérience, vous serez tenté de modifier certains paramètres, pour faire correspondre ces sources avec votre utilisation ou vos habitudes.
 
-NOTE: Il est aussi possible d'utiliser l'argument `--template`, suivie d'un argument reprenant le nom de votre projet (`<my_project>`), lors de l'initialisation d'un projet avec la commande `startproject` de `django-admin`, afin de calquer votre arborescence sur un projet existant. 
+NOTE: Il est aussi possible d'utiliser l'argument `--template`, suivie d'un argument reprenant le nom de votre projet (`<my_project>`), lors de l'initialisation d'un projet avec la commande `startproject` de `django-admin`, afin de calquer votre arborescence sur un projet existant.
 La https://docs.djangoproject.com/en/stable/ref/django-admin/#startproject[documentation] à ce sujet est assez complète.
 
 [source,bash]

source/part-3-django-concepts/admin.adoc

@@ -1,26 +1,113 @@
 == Administration
 
-Woké. On va commencer par la *partie à ne _surtout_ (__surtout__ !!) pas faire en premier dans un projet Django*. Mais on va la faire quand même: la raison principale est que cette partie est tellement puissante et performante, qu'elle pourrait laisser penser qu'il est possible de réaliser une application complète rien qu'en configurant l'administration. Mais c'est faux.
+Woké. On va commencer par la *partie à ne _surtout_ (__surtout__ !!) pas faire en premier dans un projet Django*.
+Mais on va la faire quand même: la raison principale est que cette partie est tellement puissante et performante, qu'elle pourrait laisser penser qu'il est possible de réaliser une application complète rien qu'en configurant l'administration.
+Mais c'est faux.
 
-L'administration est une sorte de tour de contrôle évoluée; elle se base sur le modèle de données programmé et construit dynamiquement les formulaires qui lui est associé. Elle joue avec les clés primaires, étrangères, les champs et types de champs par https://fr.wikipedia.org/wiki/Introspection[introspection], et présente tout ce qu'il faut pour avoir du https://fr.wikipedia.org/wiki/CRUD[CRUD], c'est-à-dire tout ce qu'il faut pour ajouter, lister, modifier ou supprimer des informations.
+L'administration est une sorte de tour de contrôle évoluée, un _back office_ sans transpirer; elle se base sur le modèle de données programmé et construit dynamiquement les formulaires qui lui est associé.
+Elle joue avec les clés primaires, étrangères, les champs et types de champs par https://fr.wikipedia.org/wiki/Introspection[introspection], et présente tout ce qu'il faut pour avoir du https://fr.wikipedia.org/wiki/CRUD[CRUD], c'est-à-dire tout ce qu'il faut pour ajouter, lister, modifier ou supprimer des informations.
 
-Son problème est qu'elle présente une courbe d'apprentissage asymptotique. Il est *très* facile d'arriver rapidement à un bon résultat, au travers d'un périmètre de configuration relativement restreint. Mais quoi que vous fassiez, il y a un moment où la courbe de paramétrage sera tellement ardue que vous aurez plus facile à développer ce que vous souhaitez ajouter en utilisant les autres concepts de Django.
+Son problème est qu'elle présente une courbe d'apprentissage asymptotique.
+Il est *très* facile d'arriver rapidement à un bon résultat, au travers d'un périmètre de configuration relativement restreint.
+Mais quoi que vous fassiez, il y a un moment où la courbe de paramétrage sera tellement ardue que vous aurez plus facile à développer ce que vous souhaitez ajouter en utilisant les autres concepts de Django.
 
-Elle doit rester dans les mains d'administrateurs ou de gestionnaires, et dans leurs mains à eux uniquement: il n'est pas question de donner des droits aux utilisateurs finaux (même si c'est extrêment tentant durant les premiers tours de roues). Indépendamment de la manière dont vous allez l'utiliser et la configurer, vous finirez par devoir développer une "vraie" application, destinée aux utilisateurs classiques, et répondant à leurs besoins uniquement.
+Cette fonctionnalité doit rester dans les mains d'administrateurs ou de gestionnaires, et dans leurs mains à eux uniquement: il n'est pas question de donner des droits aux utilisateurs finaux (même si c'est extrêment tentant durant les premiers tours de roues).
+Indépendamment de la manière dont vous allez l'utiliser et la configurer, vous finirez par devoir développer une "vraie" application, destinée aux utilisateurs classiques, et répondant à leurs besoins uniquement.
 
-Une bonne idée consiste à développer l'administration dans un premier temps, en *gardant en tête qu'il sera nécessaire de développer des concepts spécifiques*. Dans cet objectif, l'administration est un outil exceptionel, qui permet de valider un modèle, de créer des objets rapidement et de valider les liens qui existent entre eux. 
+Une bonne idée consiste à développer l'administration dans un premier temps, en *gardant en tête qu'il sera nécessaire de développer des concepts spécifiques*.
+Dans cet objectif, l'administration est un outil exceptionel, qui permet de valider un modèle, de créer des objets rapidement et de valider les liens qui existent entre eux.
 
-C'est un excellent outil de prototypage et de preuve de concept.
+C'est aussi un excellent outil de prototypage et de preuve de concept.
 
-Elle se base sur plusieurs couches que l'on a déjà (ou on va bientôt) aborder (suivant le sens de lecture que vous préférez): 
+Elle se base sur plusieurs couches que l'on a déjà (ou on va bientôt) aborder (suivant le sens de lecture que vous préférez):
 
-. Le modèle et les validateurs
+. Le modèle de données
+. Les validateurs
 . Les formulaires
 . Les widgets
 
-=== Quelques conseils
+=== Le modèle de données
 
-. Surchargez la méthode `__str__(self)` pour chaque classe que vous aurez définie dans le modèle. Cela permettra de construire une représentation textuelle pour chaque instance de votre classe. Cette information sera utilisée un peu partout dans le code, et donnera une meilleure idée de ce que l'on manipule. En plus, cette méthode est également appelée lorsque l'administration historisera une action (et comme cette étape sera inaltérable, autant qu'elle soit fixée dans le début). 
+Comme expliqué ci-dessus, le modèle de données est constité d'un ensemble de champs typés et de relations.
+L'administration permet de décrire les données qui peuvent être modifiées, en y associant un ensemble (basique) de permissions.
+
+Si vous vous rappelez de l'application que nous avions créée dans la première partie, les URLs reprenaient déjà la partie suivante:
+
+[source,python]
+----
+from django.contrib import admin
+from django.urls import path
+
+from gwift.views import wish_details
+
+urlpatterns = [
+    path('admin/', admin.site.urls), <1>
+    [...]
+]
+----
+<1> Cette URL signifie que la partie `admin` est déjà active et accessible à l'URL `<mon_site>/admin`
+
+C'est le seul prérequis pour cette partie.
+
+Chaque application nouvellement créée contient par défaut un fichier `admin.py`, dans lequel il est possible de déclarer quel ensemble de données sera accessible/éditable.
+Ainsi, si nous partons du modèle basique que nous avions détaillé plus tôt, avec des souhaits et des listes de souhaits:
+
+[source,python]
+----
+# gwift/wish/models.py
+
+from django.db import models
+
+
+class WishList(models.Model):
+    name = models.CharField(max_length=255)
+
+
+class Item(models.Model):
+    name = models.CharField(max_length=255)
+    wishlist = models.ForeignKey(WishList, on_delete=models.CASCADE)
+
+----
+
+Nous pouvons facilement arriver au résultat suivant, en ajoutant quelques lignes de configuration dans ce fichier `admin.py`:
+
+[source,python]
+----
+from django.contrib import admin
+
+from .models import Item, WishList <1>
+
+
+admin.site.register(Item) <2>
+admin.site.register(WishList)
+
+----
+<1> Nous importons les modèles que nous souhaitons gérer dans l'admin
+<2> Et nous les déclarons comme gérables. Cette dernière ligne implique aussi qu'un modèle pourrait ne pas être disponible du tout, ce qui n'activera simplement aucune opération de lecture ou modification.
+
+Il nous reste une seule étape à réaliser: créer un nouvel utilisateur.
+Pour cet exemple, notre gestion va se limiter à une gestion manuelle; nous aurons donc besoin d'un _super-utilisateur_, que nous pouvons créer grâce à la commande `python manage.py createsuperuser`.
+
+[source,bash]
+----
+λ python manage.py createsuperuser
+Username (leave blank to use 'fred'): fred
+Email address: fred@root.org
+Password: ******
+Password (again): ******
+Superuser created successfully.
+----
+
+.Connexion au site d'administration
+image::images/django/django-site-admin.png[align=center]
+
+.Administration
+image::images/django/django-site-admin-after-connection.png[align=center]
+
+
+=== Quelques conseils de base
+
+. Surchargez la méthode `__str__(self)` pour chaque classe que vous aurez définie dans le modèle. Cela permettra de construire une représentation textuelle pour chaque instance de votre classe. Cette information sera utilisée un peu partout dans le code, et donnera une meilleure idée de ce que l'on manipule. En plus, cette méthode est également appelée lorsque l'administration historisera une action (et comme cette étape sera inaltérable, autant qu'elle soit fixée dans le début).
 
 . La méthode `get_absolute_url(self)` retourne l'URL à laquelle on peut accéder pour obtenir les détails d'une instance. Par exemple:
 
@@ -52,17 +139,17 @@ https://hackernoon.com/all-you-need-to-know-about-prefetching-in-django-f9068ebe
 https://medium.com/@hakibenita/things-you-must-know-about-django-admin-as-your-app-gets-bigger-6be0b0ee9614
 
 En gros, le problème de l'admin est que si on fait des requêtes imbriquées, on va flinguer l'application et le chargement de la page.
-La solution consiste à utiliser la propriété `list_select_related` de la classe d'Admin, afin d'appliquer une jointure par défaut et 
+La solution consiste à utiliser la propriété `list_select_related` de la classe d'Admin, afin d'appliquer une jointure par défaut et
 et gagner en performances.
 
 === admin.ModelAdmin
 
-La classe `admin.ModelAdmin` que l'on retrouvera principalement dans le fichier `admin.py` de chaque application contiendra la définition de ce que l'on souhaite faire avec nos données dans l'administration. Cette classe (et sa partie Meta) 
+La classe `admin.ModelAdmin` que l'on retrouvera principalement dans le fichier `admin.py` de chaque application contiendra la définition de ce que l'on souhaite faire avec nos données dans l'administration. Cette classe (et sa partie Meta)
 
 
-=== L'affichage 
+=== L'affichage
 
-Comme l'interface d'administration fonctionne (en trèèèès) gros comme un CRUD auto-généré, on trouve par défaut la possibilité de : 
+Comme l'interface d'administration fonctionne (en trèèèès) gros comme un CRUD auto-généré, on trouve par défaut la possibilité de :
 
 . Créer de nouveaux éléments
 . Lister les éléments existants
@@ -71,7 +158,7 @@ Comme l'interface d'administration fonctionne (en trèèèès) gros comme un CRU
 
 Les affichages sont donc de deux types: en liste et par élément.
 
-Pour les affichages en liste, le plus simple consiste à jouer sur la propriété `list_display`. 
+Pour les affichages en liste, le plus simple consiste à jouer sur la propriété `list_display`.
 
 Par défaut, la première colonne va accueillir le lien vers le formulaire d'édition.
 On peut donc modifier ceci, voire créer de nouveaux liens vers d'autres éléments en construisant des URLs dynamiquement.
@@ -137,7 +224,7 @@ class Wishlist(admin.ModelAdmin):
 ----
 
 
-Et voilà : l'administration d'une liste de souhaits (_Wishlist_) pourra directement gérer des relations multiples vers des souhaits. 
+Et voilà : l'administration d'une liste de souhaits (_Wishlist_) pourra directement gérer des relations multiples vers des souhaits.
 
 
 ==== Les auto-suggestions et auto-complétions
@@ -152,7 +239,7 @@ Parler ici des `fieldsets` et montrer comment on peut regrouper des champs dans
 
 === Les actions sur des sélections
 
-Les actions permettent de partir d'une liste d'éléments, et autorisent un utilisateur à appliquer une action sur une sélection d'éléments. Par défaut, il existe déjà une action de *suppression*. 
+Les actions permettent de partir d'une liste d'éléments, et autorisent un utilisateur à appliquer une action sur une sélection d'éléments. Par défaut, il existe déjà une action de *suppression*.
 
 Les paramètres d'entrée sont :