Le livre de

Le Zen de l’administration

Fondamentalement, l’interface d’administration de Django est conçue pour une unique activité:

> Des utilisateurs de confiance éditant du contenu structuré.

Oui, c’est extrémement simple - mais cette simplicité repose sur une multitude d’hypothèses. L’entière philosophie de l’interfaace d’administration de Django provient directement de ces hypothèses, aussi allons nous plonger entre les lignes de cette phrase au cours des sections qui suivent.

Personnalisation des gabarits d’admin

Nativement, Django fourni de nombreux outils pour personnaliser les gabarits de base de l’interface d’administration, outils que nous aborderons sous peu. Pour les tâches plus évoluées (par exemple, tout ce qui nécessite un workflow personnalisé ou une granularité dans les permissions), vous devrez lire la section intitulée «Création des vues d’admin personnalisées» plus loin dans ce chapitre.

Pour l’instant, observons quelques méthodes rapides pour personnaliser l’apparence (en, par extension, le comportement) de l’interface d’administration. Le chapitre 6 couvre quelques unes des tâches courantes: «l’intégration» de l’interface d’administration dans une charte graphique différente (pour ces patrons aux mèches colorées qui détestent le bleu) et la mise en place d’un formulaire d’administration personnalisé.

Passer ce point, l’objectif implique habituellement quelques modifications des gabarits au niveau d’éléments précis. Chacunes des vues d’administration - la liste des modifications, les formulaires d’édition, les pages de confirmation de suppression et les vues d’historiques - possède un gabarit associé qui peut être outrepassé de nombreuses façons.

Premièrement, vous pouvez outrepasser globalement le gabarit. La vue d’administration cherche les gabarits utilisant le mécanisme standard de chargement des gabarits, ainsi lorsque vous créez des gabarits dans un des vos répertoires de gabarit, Django chargera ceux-ci au lieu des gabarits d’admin par défaut livrés avec Django. Ces gabarits globaux sont décrit au Tableau 17-1.

Tableau 17-1. Gabarits globaux d’admin

La plupart du temps, cependant, vous voudrez modifier le gabarit simplement pour un unique objet ou application (pas globallement). Ainsi, chaque vue d’admin cherche les modèles et les gabarits spécifiques à l’application, en premier lieu. Ces vues recherche les gabarits dans cet ordre:

• admin/<app_label>/<object_name>/<template>.html
• admin/<app_label>/<template>.html
• admin/<template>.html

Par exemple, la vue du formulaire ajout/modification pour un modèle Book au sein de l’application books cherche les gabarits dans cet ordre:

• admin/books/book/change_form.html
• admin/books/change_form.html
• admin/change_form.html

Gabarits de modèle personnalisés

La plupart du temps, vous voudrez utiliser le premier gabarit pour créer un gabarit spécifique à un modèle. La meilleure manière consiste généralement à étendre le gabarit de base et à ajouter l’information à l’un des blocs défini dans ce gabarit.

Par exemple, admettons que nous voulions ajouter un peu de texte d’aide au sommet de cette page «book». Quelque chose ressemblant à ce que montre la Figure 17-1.

Figure 17-1. Un formulaire d’édition personnalisé dans l’interface d’admin

C’est assez facile à faire: créez simplement un gabarit appelé admin/bookstore/book/change_form.html et insérez ce code:

{% extends "admin/change_form.html" %}

{% block form_top %}
  <p>Insert meaningful help message here...</p>
{% endblock %}

Tous ces gabarits définissent de nombreux blocs que vous pouvez outrepasser. Comme avec la plupart des programmes, la meilleure documentation est la code, nous vous encourageons à regarder celui des gabarits d’admin (ils sont dans django/contrib/admin/templates/) pour connaître l’information la plus à jour.

{% extends "admin/object_history.html" %}

{% block extrahead %}
    <script src="http://media.example.com/javascript/jquery.js"
    type="text/javascript"></script>
    <script type="text/javascript">

        // code to actually use jQuery here...

    </script>
{% endblock %}

Création des vues d’admin personnalisées

À ce stade, toute personne cherchant à ajouter des comportements personnalisés à l’interface d’admin de Django commence a être un peu frustrée. «Tout ce dont vous avez parlé concerne la façon de changer l’interface d’admin visuellement », entend-on pleurer. «Mais comment puis-je changer la façon dont fonctionne l’interface d’administration ?».

La première chose à comprendre est que «ce n’est pas magique». Ceci étant, rien de ce que fait l’interface d’administration n’est «spécial» - l’interface d’admin est simplement un jeu de vues (elles se trouvent dans django.contrib.admin.views) qui manipule les données comme tout autre vue.

Évidemment, il y a un peu de code là-dedans; il faut gérer les diverses options, les types de champs ainsi que les paramètres qui influencent le comportement du modèle. Ceci dit, lorsque vous réalisés que l’interface d’administration est juste un jeu de vues, ajouter des vues d’admin personnalisées devient facile à comprendre.

À titre d’exemple, ajoutons une vue «rapport de l’éditeur» à notre application «book» du chapitre 6. Nous construirons une vue d’admin qui montre la liste des livres ventilée par éditeur - un exemple assez typique de vue d’admin personalisée que vous pourriez avoir à faire.

Tout d’abord, ajoutons une vue à notre URLconf. Nous devons insérer cette ligne:

(r'^admin/books/report/$', 'mysite.books.admin_views.report'),

avant la ligne incluant les vues d’admin. Un URLconf basique pourrait ressembler à ceci:

from django.conf.urls.defaults import *

urlpatterns = patterns('',
    (r'^admin/bookstore/report/$',
    'bookstore.admin_views.report'),
    (r'^admin/', include('django.contrib.admin.urls')),
)

Pourquoi placer la vue personnalisée avant l’inclusion de l’admin ? Souvenez vous que Django traite les patrons d’URL dans l’ordre. L’inclusion de l’admin met en correspondance à peu près tout ce qui tombe sous le point d’inclusion, ainsi su nous inversons l’ordre de ces lignes, Django trouvera une vue d’admin par défaut pour ce patron, qui ne fonctionnera pas. Dans ce cas particulier, il tentera de charger une liste des modifications pour un modèle Report de l’application books, qui n’existe pas.

Dans ce cas particulier, il tentera de charger une liste des modifications pour le model Report de l’application books, qui n’existe pas.

Écrivons à présent notre vue. Pour des raisions de simplicité, nous chargerons simplement tous les livres dans le contexte et laisserons le gabarit gérer le regroupement à l’aide de la balise {% regroup %}. Créez un fichier, books/admin_views.py, avec ce code:

from mysite.books.models import Book
from django.template import RequestContext
from django.shortcuts import render_to_response
from django.contrib.admin.views.decorators import
staff_member_required


def report(request):
    return render_to_response(
        "admin/books/report.html",
        {'book_list' : Book.objects.all()},
        RequestContext(request, {}),
    )
report = staff_member_required(report)

Puisque nous avons laissé le regroupement au niveau du gabarit, cette vue reste assez simple. Cependant, il y a quelques éléments ici qui méritent quelques explications:

• nous utilisons le décorateur staff_member_required de django.contrib.admin.views.decorators. Celui-ci est similaire au décorateur login_required discuté au chapitre 12, msauf que ce décorateur vérifie aussi que l’utilisateur précisé est membre du «staff», ce qui lui donne accès à l’interface d’administration.

  Ce décorateur protège toutes les vues primitives de l’administration et fait correspondre la logique d’identification de vos vue avec le reste de l’interface d’administration.

• nous faisons le rendu d’un gabarit située sous admin/. Alors que ceci n’est pas strictement nécessaire, c’est une bonne pratique que de conserver tous vos gabarits d’administration groupés dans un dosier admin. Nous avons aussi placé le gabarit dans un répertoire appelé books conformément à notre application - il s’agit là encore d’une bonne pratique.

• nous utilisons RequestContext pour troisème paramètre (context_instance) de render_to_response. Ceci afin de s’assurer que l’information au sujet de l’utilisateur courant est disponible au niveau du gabarit.

  Lisez le chapitre 10 pour en savoir plus au sujet de RequestContext.

Pour finir, nous ferons un gabarit pour cette vue. Nous étendrons le gabarit primitif d’administration pour faire en sorte que cette vue apparaisse visuellement comme faisant partie de l’interface d’administration:

{% extends "admin/base_site.html" %}

{% block title %}List of books by publisher{% endblock %}

{% block content %}
<div id="content-main">
  <h1>List of books by publisher:</h1>
  {% regroup book_list|dictsort:"publisher.name" by publisher as
  books_by_publisher %}
  {% for publisher in books_by_publisher %}
    <h3>{{ publisher.grouper }}</h3>
    <ul>
      {% for book in publisher.list|dictsort:"title" %}
        <li>{{ book }}</li>
      {% endfor %}
    </ul>
  {% endfor %}
</div>
{% endblock %}

En étendant admin/base_site.html, nous obtenons l’apparence de l’interface d’admin de Django - gracieusement. La Figure 17-2 montre ce à quoi ressemble le résutlat.

Figure 17-2. Une vue d’admin personnalisée «livres par éditeur»

Vous pouvez utiliser cette technique pour ajouter tout ce dont vous rêvez à l’interface d’administration. Souvenez vous que ces vues personnalisées sont simplement des vues Django normales; vous pouvez utiliser toutes les techniques que vous avez apprise dans le reste de ce livre pour fournir une interface d’admin aussi complexe que vos besoins.

Nous terminons ce chapitre avec quelques idées de personnalisation des vues d’administration.

Écraser les vues primitives

Parfois les vues d’administration proposées par défaut ne font pas l’affaire. Vous pouvez aisément les substituer avec vos propres vues personnalisées, et ce à tous les niveaux de l’interface d’administration; laissez simplement votre URL «masquer» celle par défaut de l’administration. Ceci dit, si votre vue arrive avant la vue d’admin par défaut au sein de votre URLconf, votre vue sera appellée à la place de celle par défaut.

Par exemple, nous pouvons remplacer la vue primitive permettant de «créer» un livre par un formulaire qui laisse l’auteur siasir un ISBN. Nous pouvons ensuite chercher les informations sur ce livre à partir de http://isbn.nu/ et créer l’objet automatiquement.

Le code pour une telle vue est laissé à titre d’exercice au lecteur, la partie importante se trouvant dans cet extrait d’URLconf:

(r'^admin/bookstore/book/add/$', 'mysite.books.admin_views.add_by_isbn'),

Si cette partie est placée avant les URLs d’admin dans votre URLconf, la vue add_by_isbn remplacera complétement la vue standard d’admin.

Nous pouvons suivre un parcours similaire pour remplacer une page de confirmation de suppression, une page d’édition, ou tout autre partie de l’interface d’administration.

Et ensuite ?

Si l’Anglais est votre langue maternelle - et nous espérons que la plupart des lecteurs de ce livre le sont - vou pourriez ne pas avoir noté une des fonctionnalité les plus sympatiques de l’interface d’admin: elle est disponible dans plus de 40 langues ! Ceci est rendu possible par le framework d’internationalisation de DJango (et le dur labeur des traducteurs bénévoles de Django). Le chapitre suivant détaille la façon d’utiliser ce framework pour fournir des sites Django localisés.

Avanti!

<< précédent ◊ suivant >>