Le livre de

Activer l’interface d’administration

Nous pensons que l’interface d’administration est la partie la plus sympatique de Django — et la plupart des Djangonautes s’accordent à le dire — mais puisque tout le monde n’en a pas besoin, c’est une partie optionnelle. Cela signifie que vous devrez suivre trois étapes pour l’activer :

1. Ajoutez les métadonnées d’administration à votre modèle.

   Tous les modèles ne peuvent (ou ne doivent) pas êtres éditables par les administrateurs du site, vous devez donc «tatouer » les modèles qui doivent offrir une interface d’administration. Vous faites cela en ajoutant une classe interne d’Admin à vos modèles (à côté de la classe Meta, si vous en avez une). En résumé, pour ajouter une interface d’administration à notre modèle Book du chapitre précédent, nous faisons ceci :

   class Book(models.Model):
       title = models.CharField(maxlength=100)
       authors = models.ManyToManyField(Author)
       publisher = models.ForeignKey(Publisher)
       publication_date = models.DateField()
       num_pages = models.IntegerField(blank=True, null=True)
   
       def __str__(self):
           return self.title
   
       class Admin: pass
   

   La déclaration Admin marque la classe comme ayant une interface d’administration. Il y a de nombreuses options que vous pouvez ajouter à Admin , mais pour le moment nous resterons avec le comportement par défaut, en ajoutant pass à la fin de façon à signifier à Python que la classe Admin est vide.

   Si vous suivez cet exemple avec votre propre code, c’est probablement une bonne idée d’ajouter à présent une déclaration Admin aux classes Publisher et Author .

2. Installer l’application d’administration. Faites le en ajoutant `` “django.contrib.admin” `` à votre paramètre INSTALLED_APPS .

3. Si vous avez suivi depuis le début, assurez vous que "django.contrib.sessions", "django.contrib.auth", et "django.contrib.contenttypes" ne soient pas commentées, car l’application d’administration repose sur celles-ci. Décommentez aussi toutes les lignes du tuple MIDDLEWARE_CLASSES et effacez le paramètre TEMPLATE_CONTEXT_PROCESSOR pour lui permettre de reprendre les valeurs par défaut.

4. Lancez python manage.py syncdb. Cette étape installera les tables supplémentaires dans la base de données.

   Note

   Lorsque vous lancez le premier syncdb avec "django.contrib.auth"``dans INSTALLED_APPS,  vous serez invité à créer un super utilisateur. Si vous ne le faite pas à ce moment, vous devrez lancer ``django/contrib/auth/bin/create_superuser.py pour en créer un. Dans le cas contraire, vous ne serez pas autorisé à vous connecter à l’interface d’administration.

5. Ajoutez le patron d’URL à votre urls.py. Si vous continuez à utiliser celui crée par startproject, le patron pour les URLs d’administration doit déja être présent, mais commenté. Quoi qu’il en soit, vos patron d’URL doivent ressembler à ceci :

   from django.conf.urls.defaults import *
   
   urlpatterns = patterns('',
       (r'^admin/', include('django.contrib.admin.urls')),
   )
   

C’est fait. À présent, lancez python manage.py runserver pour démarrer le serveur de développement. Vous devriez voir quelquechose comme ceci :

Validating models...
0 errors found.

Django version 0.96, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

À présent vous pouver visiter l’URL qui vous est donné par Django (http://127.0.0.1:8000/admin/ dans notre précédent exemple), vous connecter, et vous amuser un peu.

Utiliser l’interface d’administration

L’interface d’admin est conçue pour être utilisée par des utilisateurs non-techniciens, et à ce titre elle se doit d’être intuitive. Néanmoins, quelques notes sur les caractéristiques de l’interface d’administration sont prévues.

La première chose que vous verrez sera l’écran de connexion, comme le montre la Figure 6-1.

Figure 6-1. L’écran de connexion de Django

Vous utiliserez le nom d’utilisateur et le mot de passe que vous avez défini lors de l’ajout de votre super utilisateur. Une fois connecté, vous verrez que vous avez la possibilité de gérer les utilisateurs, les groupes et les permissions (plus de détails dans quelques instants).

Chaque objet possédant une déclaration Admin s’affiche sur la page d’accueil principal, comme le montre la Figure 6-2.

Figure 6-2. La page principale d’administration sous Django

Les liens permettant d’ajouter ou de changer les objets mènent à deux pages que nous considérons comme les objets change lists et edit forms. Les « change lists » sont essentiellement des pages indexant les objets dans le système, comme le montre la Figure 6-3.

Figure 6-3. Une vue typique de « change list »

De nombreuses options contrôlent les champs qui apparaissent dans ces listes. Elles contrôlent aussi l’apparence de fonctionnalités supplémentaires tels que des champs dates, de champs de recherche, des interfaces filtrantes. Nous discuterons de ces fonctionnalités plus en détail dans un court instant.

Les formulaires d’édition sont utilisés pour modifier des objets existants et en créer de nouveaux (consultez la Figure 6-4). Chaque champs définis dans votre modèle apparaissent ici, et vous noterez que les champs de type différents utilisent des widgets différents (par exemplen les champs date/heure ont des actions de calendriers, les clefs étrangères proposent des boîtes de sélections, etc. ).

Figure 6-4. Un formulaire d’édition typique

Vous noterez que l’interface d’admin gère aussi la validation des entrées pour vous. Essayer de laisser un champ requis vide ou de mette une heure invalide dans un champ heure, et vous verrez ces erreurs lorsque vous tenterez d’enregistrer, comme le montre la Figure 6-5.

Figure 6-5. Un formulaire d’édition affichant les erreurs.

Lorsque vous éditez un objet existant, vous remarquerez un bouton « History » dans le coin supérieure droit de la fenêtre. Chaque changement effectué au travers de l’interface d’administration est enregistré, et vous pouvez examiner cet enregistrement en cliquant sur ce bouton (voir la Figure 6-6).

Figure 6-6. Page d’historique d’un objet sous Django.

Lorsque vous effacez un objet existant, l’interface d’administration vous demande de confirmer la suppression pour éviter les erreurs couteuses. La suppression cascade ; la page de confirmation vous montre tous les objets relatifs qui seront aussi supprimés. (see Figure 6-7).

Figure 6-7. page de confirmation de suppression sous Django

Personnalisation de l’interface d’administration

Vous pouvez personnaliser l’apparence de l’interface et son comportement de nombreuses façons. Nous n’aborderons dans cette partie que ceux qui sont en relation avec notre modèle Book. Le chapitre 17 couvre la personnalisation de l’interface d’administration en détail.

En l’état actuel, la liste des modification pour nos livres ne montre que la représentation textuelle du modèle que nous avons ajouté à son __str__. Ceci fonctionne bien pour quelques livres, mais si nous avions des centaines voir des milliers de livres, il deviendrait très difficile de localiser une seule aiguille dans une bottre de foin. Cependant, nous pouvons aisément ajouter quelques fonctions d’affichage, de recherche et de filtrage à cette interface. Modifiez la déclaration Admin comme suit :

class Book(models.Model):
    title = models.CharField(maxlength=100)
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    publication_date = models.DateField()

    class Admin:
        list_display = ('title', 'publisher',
        'publication_date')
        list_filter = ('publisher', 'publication_date')
        ordering = ('-publication_date',)
        search_fields = ('title',)

Ces quatres lignes de code modifient dramatiquement notre interface de liste, comme le montre la Figure 6-8.

Figure 6-8. Page affichant la liste modifiée des changements

chacune de ces lignes renseigne l’interface d’admin sur la manière de construire une partie de l’interface :

• L’option list_display contrôle les colonnes qui doivent apparaitres dans le tableau de la liste des changements. Par défaut, l’affichage de la liste des changements se compose d’une seule colonne qui contient la représentation textuelle de l’objet. Ici, nous avons modifiés cela de façon à montrer le titre, l’éditeur et la date de publication.

• L’option list_filter crée la barre de filtrage sur la droite de la liste. Nous avons autorisés le filtrage des dates (qui vous permet de voir uniquement les livres publiés la semaine dernière, le mois dernier, etc.) et des éditeurs.

  Vous pouvez demander à l’interface d’administration de filtrer n’importe quel champ, mais les clefs étrangères, les dates, les booléens et les champs avec un attribut choices fonctionnent le mieux. Les filtres fonctionnent dès l’instant qu’il y a au moins 2 valeurs à choisir.

• L’option ordering contrôle l’ordre dans lequel les objets sont présentés dans l’interface d’administration. C’est tout simplement une liste des champs pour lequels vous voulez ordonner les résultats ; en préfixant le champ avec un signe moins, vous inversez l’ordre courant. Dans cet exemple, nous classons par date de publication, les plus récents en premier.

• Finalement, l’option search_fields crée un champ qui autorise les recherches textuelles. Il permet les recherches psur le champ title (vous pouvez donc saisir Django pour afficher tous les livres ayant « Django » dans le titre).

En utilisant ces options (et celles décrites au chapitre 12), vous pouvez, avec quelques lignes de code, faire une interface puissante et prête à l’emploi pour l’édition de données.

Personnaliser l’ergonomie de l’interface d’administration

Évidemment, avoir le texte « Django administration » en haut de chaque page d’administration est ridicule. Il s’agit juste d’un texte de démonstration.

Il est toutefois facile de modifier cela, en utilisant le système de gabarit de Django. Le site d’administration de Django lui même, ainsi que ses interfaces, utilisent le système de gabarit de Django. (Le système de gabarit a été abordé au chapitre 4).

Comme nous l’avons expliqué au chapitre 4, le paramètre TEMPLATE_DIRS spécifie une liste de répertoires à vérifier lorsque Django charge les gabarits. Pour personaliser les gabarits de l’interface d’administration de Django, copiez simplement le gabarit de l’interface d’admin fourni par la distribution Django dans l’un de vos répertoires spécifiés dans TEMPLATE_DIRS.

Le site d’administration trouve l’en-tête « Django administration » en cherchant le gabarit admin/base_site.html. Par défaut, ce gabarit réside dans le répertoire django/contrib/admin/templates, que vous pouvez trouver en regardant dans votre répertoire Python site-packages ou à l’endroit où vous avez installé Django. Pour personnaliser ce gabarit base_site.html, copiez le dans le sous-dossier admin du répertoire que vous indiquez dans votre TEMPLATE_DIRS. Par exemple, si votre TEMPLATE_DIRS inclu "/home/mytemplates", copiez alors django/contrib/admin/templates/admin/base_site.html dans /home/mytemplates/admin/base_site.html. N’oubliez pas ce sous-répertoire admin.

Ensuite, éditez simplement le nouveau fichier admin/base_site.html et remplacez le texte générique de Django par votre propre nom de site.

Notez que tous les gabarits d’administration de Django peuvent être outrepassés. Pour ce faire, il suffit de faire la même chose qu’avec base_site.html : copiez le depuis le répertoire par défaut dans votre repertoire personnalisé et effectuez les changements sur cette copie.

Vous devez vous demander comment, si TEMPLATE_DIRS était vide par défaut, Django a trouvé les gabarits de l’interface d’admin. La réponse est que Django regarde automatiquement les gabarits situés dans le sous-répertoire templates/ de chaque application, en dernier recours. Consultez « Écrire des chargeurs de gabarit personnalisés » au chapitre 10 pour plus d’information sur son fonctionnement.

Personnaliser la page d’index de l’interface d’administration

De la même façon, vous pourriez vouloir personnaliser l’ergonomie de la page d’index de l’interface d’administration. Par défaut, elle affiche toutes les applications disponibles, d’après votre paramètre INSTALLED_APPS, triées selon le nom de l’application. Vous pourriez cependant, vouloir changer cet ordre pour rendre plus facile à trouver l’application que vous recherchez. Après tout, l’index est probablement l’endroit le plus important de l’interface d’administration, elle doit donc être facile d’utilisation.

Le gabarit à personnaliser est admin/index.html. (Souvenez vous de copier admin/index.html dans votre répertoire de gabarit comme dans l’exemple précédent). Éditez le fichier, et vous verrez qu’il utilise une balise de gabarit appelé {% get_admin_app_list as app_list %}. Cette balise récupère toutes les applications Django installées. Au lieu d’utilser la balise, vous pouvez coder en dure les liens vers les objets spécifiques aux pages d’administration de la façon qui vous paraît être la meilleure. Si coder en dure des liens ne vous attire pas, regarder les détails du chapitre 10 au sujet de l’implémentation de vos propre balise de gabarit.

Django offre un autre raccourcis à ce niveau ; Lancez la commande python manage.py adminindex <appli> pour obtenir un morceau de code du gabarit afin de l’inclure dans le gabarit de l’index d’administration. C’est un point de départ très utile.

Pour des détails complet sur la personnalisation de l’interface d’administration du site sous Django en général, voyez le chapitre 17.

Quand et pourquoi utiliser l’interface d’administration

Nous pensons que l’interface d’administration de Django est assez spectaculaire. En fait, nous l’appellons « une des fonctionnalités qui tue » de Django. Cependant, on nous demande souvent des « cas d’utilisation » pour l’interface d’administration — Quand faisons nous ceci, et pourquoi ? Au fil du temps, nous avons découvert de nombreux patrons d’utilisation de l’interface d’admin que nous pensons être utiles.

Évidemment, l’interface d’admin est extrémement utile pour éditer des données (Qui l’eût cru !). Si vous avez toute sorte de tâches de saisie des données, l’interface d’admin est simplement imbattable. Nous suspectons la grande majorité de nos lecteurs d’avoir toute une série de tâches de saisie à faire.

L’interface d’admin de Django est particulièrement brillante lorsque des utilisateurs non techniciens doivent pouvoir entrer des données ; C’est le but de cette fonctionnalité après tout. Au sein du journal où Django a été développé, le développement d’une fonctionnalité en ligne — un compte rendu spécial sur la qualité de l’eau dans la municipalité — donne quelque chose comme ceci :

• Le journaliste responsable rencontre l’un des développeurs et présente les données disponibles.
• Le développeur construit un modèle autour de ces données puis ouvre l’interface d’administration au reporter.
• Pendant que celui-ci entre les données, le programmeur peut se concentrer sur l’interface d’accès publique (la partie amusante !).

Autrement dit, la raison d’être de l’interface d’admin de Django est de faciliter simultanément le travail des producteurs de contenu et des programmeurs.

Cependant, au-delà de ces tâches évidentes de saisie des données, nous trouvons l’interface d’administration dans d’autre cas :

• pour inspecter le modèle de données : La première chose que nous faisons lorsque nous avons définis un nouveau modèle est de l’appeler depuis l’interface d’admin et de saisir des données factices. C’est généralement ainsi que nous décelons les erreurs de structure de données ; avoir une interface graphique pour un modèle révèle rapidement les problèmes.
• Gérer des données exterieures : Il y a très peu de saisie de données associées à un site tel que http://chicagocrime.org, puisque la plupart des informations proviennent d’une source automatisée. Ainsi, lorsque des problèmes avec l’acquisition automatique des données apparaissent, il est pratique de pouvoir les éditer facilement.

Et ensuite ?

Jusqu’à présent nous avons créés quelques modèles et configurés une interface dernier-cri pour éditer les données. Dans le chapitre suivant , nous irons dans le cœur du développement web: la création et la gestion des formulaires.

<< précédent ◊ suivant >>