root/docs/trunk/overview.txt

=======================
Django d'un coup d'oeil
=======================

Parce que Django a été développé dans une salle de rédaction dont l'environnement
change rapidement, il a été conçu pour effectuer les tâches courantes du développement
web rapidement et facilement. Vous trouverez ici une introduction informelle sur comment
écrire une application web autour d'une base de données avec Django.

Le but de ce document est de vous donner suffisamment de détails techniques pour 
comprendre comment fonctionne Django, mais il n'est en rien un tutoriel ou de référence. 
Merci de vous référer à la documentation_ Django, bien plus complÚte, quand vous serez prêt 
à commencer un projet.

.. _documentation: ../

Concevez votre modÚle
=====================

Bien que vous pouviez utiliser Django sans base de données, il contient une couche de 
correspondance Objet-Relationnel (ORM) dans laquelle vous décrivez la structure de votre 
base de données en code Python.

La syntaxe du modÚle de données permet de représenter vos modÚles de plusieurs façons
-- jusqu'ici, il a le mérite de résoudre nos pires problÚmes de schémas de base de 
données depuis 2 ans. Voici un rapide exemple ::

    class Reporter(models.Model):
        full_name = models.CharField(maxlength=70)

        def __str__(self):
            return self.full_name

    class Article(models.Model):
        pub_date = models.DateTimeField()
        headline = models.CharField(maxlength=200)
        article = models.TextField()
        reporter = models.ForeignKey(Reporter)

        def __str__(self):
            return self.headline

Installez-le
============

Ensuite, lancez l'utilitaire en ligne de commande de Django pour créer automatiquement 
vos tables dans la base de données ::

    manage.py syncdb

La commande ``syncdb`` examine tous vos modÚles disponibles et crée les 
tables qui n'existent pas encore dans votre base de données.

Appréciez l'API ???
=====================

Avec cela, vous avez gratuitement une API Python complÚte pour accéder à vos données.
L'API est créée à la volée : aucune génération de code n'est nécessaire ::

    >>> from mysite.models import Reporter, Article

    # Aucun reporter n'est encore dans le systÚme.
    >>> Reporter.objects.all()
    []

    # Créons un nouveau reporter
    >>> r = Reporter(full_name='John Smith')

    # Sauvegardons l'objet en base de données. Il faut appeler save() explicitement.
    >>> r.save()

    # Il a désormais un ID.
    >>> r.id
    1

    # Maintenant, le nouveau reporter est dans la base de données.
    >>> Reporter.objects.all()
    [John Smith]

    # Les champs sont représentés comme des attributs d'objets Python.
    >>> r.full_name
    'John Smith'

    # Django fournit une API riche pour la consultation de votre base de données.
    >>> Reporter.objects.get(id=1)
    John Smith
    >>> Reporter.objects.get(full_name__startswith='John')
    John Smith
    >>> Reporter.objects.get(full_name__contains='mith')
    John Smith
    >>> Reporter.objects.get(id=2)
    Traceback (most recent call last):
        ...
    DoesNotExist: Reporter does not exist for {'id__exact': 2}

    # Créons un article.
    >>> from datetime import datetime
    >>> a = Article(pub_date=datetime.now(), headline='Django is cool',
    ...     article='Yeah.', reporter=r)
    >>> a.save()

    # L'article est désormais en base de données
    >>> Article.objects.all()
    [Django is cool]

    # Les objets Article ont accÚs via l'API aux objets Reporter associés.
    >>> r = a.reporter
    >>> r.full_name
    'John Smith'

    # Et vice versa : les objets Reporter ont accÚs via l'API aux objets Article.
    >>> r.article_set.all()
    [Django is cool]

    # L'API suit les liens en fonction de vos besoins, effectuant les JOINs
    # pour vous en arriÚre plan.
    # Ceci trouve tous les articles d'un reporter dont le nom commence par "John".
    >>> Article.objects.filter(reporter__full_name__startswith="John")
    [Django is cool]

    # Changeons un objet en modifiant un de ses attributs puis appelons save().
    >>> r.full_name = 'Billy Goat'
    >>> r.save()

    # Effaçons un objet avec delete().
    >>> r.delete()

Une interface d'administration dynamique, complÚte et configurable -- pas juste un échafaudage (scaffolding)
============================================================================================================

Une fois vos modÚles définis, Django peut automatiquement créer une interface
d'administration professionnelle et prête à l'emploi -- un site web qui laisse
un utilisateur authentifié ajouter, modifier ou supprimer des objets. C'est
aussi simple que d'ajouter une ligne de code dans vos classes de modÚles ::

    class Article(models.Model):
        pub_date = models.DateTimeField()
        headline = models.CharField(maxlength=200)
        article = models.TextField()
        reporter = models.ForeignKey(Reporter)
        class Admin: pass

La philosophie ici est que votre site est édité par une équipe, ou un client,
ou même seulement vous -- et vous ne souhaitez pas vous occuper de concevoir 
une interface ne servant qu'à gérer le contenu.

Une mise en œuvre typique d'une application Django est de créer des modÚles
puis d'avoir une interface d'administration utilisable le plus rapidement
possible, afin que votre équipe (ou vos clients) puisse(nt) commencer à entrer des
données. Ensuite, développez la façon dont les données seront présentées au public.

Concevez vos URLs
=================

Des URLs propres et élégantes sont d'importants détails dans une application
web de haute qualité. Django encourage l'utilisation de belles URL et n'y ajoute
pas d'horribles choses dans vos URLs, comme ``.php`` ou ``.asp``.

Pour concevoir des URLs pour votre application, vous créez un module Python
appelé URLconf. Véritable table des matiÚres de votre application, il contient
simplement la correspondance entre le motif de vos URLs et les fonctions
callback Python. URLconfs sert également à séparer les URLs du code Python.

Voici ce à quoi URLconf peut ressembler pour l'exemple ``Reporter``/``Article``
présenté plus haut ::

    from django.conf.urls.defaults import *

    urlpatterns = patterns('',
        (r'^/articles/(\d{4})/$', 'mysite.views.year_archive'),
        (r'^/articles/(\d{4})/(\d{2})/$', 'mysite.views.month_archive'),
        (r'^/articles/(\d{4})/(\d{2})/(\d+)/$', 'mysite.views.article_detail'),
    )

Le code ci-dessus fait correspondre les URLs, de simples expressions réguliÚres,
à l'emplacement des fonctions callback Python (les "vues"). Les expressions
réguliÚres utilisent des parenthÚses pour "capturer" des valeurs à partir des URLs.
Quand un utilisateur demande une page, Django passe chaque motif en revue, dans
l'ordre, et s'arrête sur la premiÚre qui correspond à l'URL demandée. (Si aucun
motif ne correspond, Django appelle une vue spéciale 404.) C'est extrêmement 
rapide car les expressions réguliÚres sont compilées au chargement.

Une fois qu'un des motifs convient, Django importe et appelle la vue correspondante, 
qui est une simple fonction Python. Chaque vue se voit passer en paramÚtre un
objet request -- qui contient les méta-données de la requête -- et les valeurs
capturées par le motif (l'expression réguliÚre).

Par exemple, si un utilisateur demande l'URL "/articles/2005/05/39323/", Django
va appeler la fonction ``mysite.views.article_detail(request,
'2005', '05', '39323')``.

Ecrivez vos vues
================

Chaque vue s'occupe de faire une de ces deux choses : Retourner un objet
``HttpResponse`` contenant le contenu de la page demandée, ou bien lever
une exception comme une page ``Http404``. Pour le reste, c'est à vous de
jouer.

En général, une vue récupÚre des données en fonction des paramÚtres, charge un
gabarit (template) et interprÚte le gabarit avec les données récupérées. Voici un exemple
pour le ``year_archive`` vu précédemment ::

    def year_archive(request, year):
        a_list = Article.objects.filter(pub_date__year=year)
        return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list})

Cet exemple utilise le systÚme de gabarits de Django, qui a plusieurs
fonctionnalités poussées mais s'efforce de rester simple pour que des
non-programmeurs puissent l'utiliser.

Concevez vos gabarits
======================

Le code ci-dessus charge le gabarit ``news/year_archive.html``.

Django recherche les gabarits à un endroit précis, ce qui vous permet de minimiser
les redondances parmi les gabarits. Dans vos réglages Django, vous précisez une
liste de répertoires à parcourir pour les gabarits. Si un gabarit n'existe pas
dans le premier répertoire, il vérifie le suivant, et ainsi de suite.

Disons que le gabarit ``news/article_detail.html`` a été trouvé. Voici à quoi
il pourrait ressembler ::

    {% extends "base.html" %}

    {% block title %}Articles for {{ year }}{% endblock %}

    {% block content %}
    <h1>Articles for {{ year }}</h1>

    {% for article in article_list %}
    <p>{{ article.headline }}</p>
    <p>By {{ article.reporter.full_name }}</p>
    <p>Published {{ article.pub_date|date:"F j, Y" }}</p>
    {% endfor %}
    {% endblock %}

Les variables sont entourées par des doubles accolades. ``{{ article.headline }}``
signifie "Affiche la valeur de l'attribut headline de l'article". Mais les points
ne sont pas seulement utilisés pour consulter un attribut : ils peuvent aussi faire
des recherches sur les clés d'un dictionnaire, des recherches sur un index ou des appels de 
fonction.

Notez que ``{{ article.pub_date|date:"F j, Y" }}`` utilise un "tube" Ã  la Unix
(le caractÚre "|"). C'est ce qu'on appelle un filtre, et c'est un des moyens de
filtrer la valeur d'une variable. Dans ce cas, le filtre date formate un objet
datetime Python dans le format donné (comme on peut le trouver dans la fonction
date de PHP; oui, il y'a une bonne idée dans PHP).

Vous pouvez cumuler autant de filtres que vous le souhaitez. Vous pouvez écrire
vos propres filtres. Vous pouvez écrire des tags personnalisés, qui exécutent 
votre code Python en arriÚre plan.

Enfin, Django utilise un concept d'héritage de gabarits : c'est ce que fait
``{% extends "base.html" %}``. Cela signifie : "Charge d'abord le gabarit
appelé 'base', qui définit certains blocs (block), puis remplis-les avec le contenu
des blocs suivants". En bref, cela réduit considérablement les redondances dans 
vos gabarits : chaque gabarit ne définit que ce qui lui est propre (unicité).

Voici à quoi pourrait ressembler le gabarit "base.html" ::

    <html>
    <head>
        <title>{% block title %}{% endblock %}</title>
    </head>
    <body>
        <img src="sitelogo.gif" alt="Logo" />
        {% block content %}{% endblock %}
    </body>
    </html>

Pour simplifier, ce gabarit définit le look-and-feel du site (avec le logo),
et laisse des "trous" que les gabarits fils rempliront. Cela permet de changer
le design juste en modifiant un simple fichier -- le gabarit de base.

Il vous permet aussi de créer plusieurs versions du site, avec différents 
gabarits de base, en réutilisant les gabarits fils. Les créateurs de Django
ont utilisés cette technique pour créer de façon étonnante plusieurs versions
pour téléphones portables de sites -- simplement en créant un nouveau gabarit
de base.

Notez que vous n'êtes pas obligé d'utiliser le systÚme de gabarits de Django
si vous en préférez un autre. Bien que le systÚme de gabarit soit particuliÚrement
bien intégré avec le model en couches de Django, rien ne vous force à l'utiliser.
Pour cette raison, vous n'êtes pas non plus obligé d'utiliser l'API de bases
de données de Django. Vous pouvez utiliser une autre couche d'abstraction pour
votre base de données, vous pouvez lire des fichiers XML, vous pouvez lire des
fichiers sur votre disque, ou tout ce que vous voulez. Chaque partie de Django
-- modÚles, vues, gabarits -- est indépendante des autres.

Ce n'est que la face visible de l'iceberg
=========================================

Ceci n'était qu'un bref aperçu des fonctionnalités de Django. D'autres 
fonctionnalités utiles sont:

    * Un systÚme de cache qui s'intÚgre avec MemCached ou d'autre backends.
    * Un framework de syndication qui rend la création de flux RSS ou Atom aussi
      simple a écrire que de petites classes Python.
    * Des fonctionnalités d'auto-génération de la partie admin encore plus sexy --
      cet aperçu n'a qu'éraflé la surface.

Les prochaines étapes évidentes sont pour vous de `télécharger Django`, de lire
`le tutoriel`_ et de rejoindre `la communauté`_. Merci pour votre intérêt !

.. _télécharger Django: http://www.django-fr.org/telechargement/
.. _le tutoriel: http://www.django-fr.org/documentation/tutorial01/
.. _la communauté: http://www.djangoproject.com/community/