Le fichier urls.py : routage d'URL avec Django

Nous allons voir sur cette page comment créer un contrôleur frontal sous Django, en utilisant le fichier urls.py. Le fichier urls.py contient les routes du projet : il dispatche les requêtes vers les contrôleurs adéquats.

Le fichier urls.py

Sous Django, chaque projet dispose d'un contrôleur frontal.

Dans le cadre de notre projet miage_scrum, un fichier urls.py existe donc par défaut dans le répertoire miage_scrum/miage_scrum/.

Délégation aux applications

Pour rendre les applications très modulaires et réutilisables, il est possible de faire en sorte que le projet délègue une partie de la gestion des règles d'aiguillages à différentes applications. Ainsi, chaque application est responsable du routage interne des URL la concernant.

Dans le cadre de notre projet, l'ensemble des règles relatives aux backlogs, au dashboard, etc. sera géré par l'application chistera. Django implémente ceci de manière très élégante, en permettant la création d'un fichier urls.py dans le répertoire de l'application elle-même, puis en aiguillant un ensemble de requêtes depuis le contrôleur frontal d'un projet vers le contrôleur frontal de l'application.

Voyons à présent de quoi il en retourne concrètement.

Écriture du contrôleur frontal du projet

Commençons par écrire le contrôleur frontal du projet… ou plutôt le compléter, car nous l'avons déjà édité pour activer l'interface d'administration par scaffolding, rappelez-vous !

miage_scrum/miage_scrum/urls.py

from django.conf.urls import patterns, include, url

from django.contrib import admin
admin.autodiscover()

urlpatterns = patterns('',
    url(r'^admin/', include(admin.site.urls)),
    url(r'^', include('chistera.urls', namespace='chistera', app_name='chistera')),
)

Nous avons simplement ajouté une ligne au fichier existant. Cette ligne permet en substance de dire à Django : « Je veux que tu rediriges toutes les requêtes faites à la racine (^) vers le contrôleur frontal de l'application « chistera » qui est défini dans le module chistera.urls. Et, temps qu'on y est, je souhaite pouvoir faire référence à ces routes par la suite via un espace de nom qui s'appellera chistera. »

Il nous reste maintenant à (enfin !) définir nos routes vers les contrôleurs dédiés. Nous allons le faire dans le fichier urls.py de l'application.

Écriture du contrôleur frontal d'une application

Dans le répertoire de l'application, créons un fichier nommé urls.py, et écrivons-y nos règles de routage :

chistera/urls.py

from django.conf.urls import patterns, url

urlpatterns = patterns('',
    url(r'^dashboard/$', 'chistera.views.dashboard', name='dashboard'),
    url(r'^backlog/(?P<backlog_id>[0-9]+)/$', 'chistera.views.backlog', name='backlog'),
)

Comme vous le remarquez, chaque règle de routage est définie selon la syntaxe suivante : url(pattern, contrôleur de destination, nom). :

Le pattern est en fait une expression régulière (comme c'est souvent le cas dans les frameworks MVC). Une des force est ici l'utilisation des groupes nommés rendus possibles par Python : par exemple pour backlog, nous disons ici que le pattern d'URL contient une variable composée de chiffres, que l'on nomme explicitement backlog_id.
Le contrôleur de destination est une fonction définie dans le fichier des contrôleurs (views) de l'application. Nous verrons plus tard de quelle manière les contrôleurs sont écrits. Ce que vous devez savoir maintenant, c'est que la fonction représentant le contrôleur se verra passer en paramètre(s) l'ensemble des variables nommées dans le pattern. Par exemple, pour backlog, la fonction chistera.views.backlog() recevra un paramètre nommé… backlog_id. Logique non ?
Le nom de la règle de routage est utilisé pour le routage inverse. Étant donné le contrôleur chistera.views.dashboard, il est ainsi possible de retrouver l'URL dashboard/ grâce à la fonction reverse() de Django à qui l'on passe le nom de la règle de routage dans son espace de nom : reverse('chistera:dashboard') retournera dashboard/. Idéal pour ne jamais hard-coder d'URL et rester DRY !

Routage d'URL : check !

OK, notre contrôleur frontal est en place. Essayons d'accéder à l'une des URL définies pour voir ce qui se passe :

Pas content Django ! Normal, en fait : nous lui avons indiqué une route qui mène à une destination inexistante, ce qui rend le voyage désagréable. Il ne nous reste plus qu'à écrire les contrôleurs adéquats, ce qui sera l'objet du prochain tutoriel.

Testez vos connaissances…

En Django, on peut définir un contrôleur frontal au niveau…

D'une application.
D'un contrôleur.
D'une vue.
D'un projet.

Dans la déclaration url(r'^dashboard/$', 'chistera.views.dashboard', name='dashboard'), à quoi sert le paramètre name ?

Il sert simplement à ajouter de la lisibilité au code, ce qui est important en Python.
Il sert à nommer l'URL pour pouvoir y faire référence plus tard via reverse().

Pourquoi utilise-t-on des expressions régulières pour définir les routes dans un contrôleur frontal ?

Parce qu'on n'a pas le choix.
On les utilise quand les URLs à traiter comporte une partie variable (un id ou un slug).
On ne peut pas utiliser d'expression régulière dans un pattern d'URL Django.
Car le composant de gestion des URLs est défini dans le module Python re.