# Documentation Django 3.1.9.dev

# Coup d’œil sur Django

Du fait que Django a été développé dans un environnement de rédaction avec des délais très courts, il a été conçu pour rendre les tâches habituelles du développement Web rapides et simples. Voici un bref aperçu sur la manière d’écrire une application utilisant une base de données avec Django.

Le but de ce document est de vous donner assez de détails techniques pour comprendre comment fonctionne Django, mais il n’a pas pour but d’être un didacticiel ou une référence – mais nous avons cela aussi ! Quand vous êtes prêt à commencer un projet, vous pouvez démarrer avec le tutoriel ou vous plonger dans une documentation plus détaillée.

## Concevez votre modèle

Bien que vous puissiez utiliser Django sans base de données, il est livré avec un mapping objet-relationnel avec lequel vous décrivez la structure de votre base de données avec du code Python.

La syntaxe de modélisation des données offre un moyen élégant de représenter vos modèles – jusqu’ici, cela a résolu bien des années de problèmes de schéma de base de données. Voici un exemple rapide :

monsite/news/models.py

    from django.db import models

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

        def __str__(self):
            return self.full_name

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

        def __str__(self):
            return self.headline

## Déployez-le

Ensuite, lancez les utilitaires Django en ligne de commande pour créer automatiquement les tables de la base de données :

/ 

    $ python manage.py makemigrations
    $ python manage.py migrate

    ...\> py manage.py makemigrations
    ...\> py manage.py migrate

La commande `makemigrations` examine tous les modèles disponibles et crée des migrations pour les tables de base de données qui n’existent pas encore. `migrate` exécute ces migrations et crée les tables dans la base de données. Le système des migrations met à votre disposition d’autres possibilités de gestion de votre schéma de base de données.

## Profitez de l’API qui vous est offerte

Dès lors, vous avez gratuitement accès à une API Python riche pour manipuler vos données. L’API est générée à la volée, sans avoir besoin d’écrire du code

    # Import the models we created from our "news" app
    >>> from news.models import Article, Reporter

    # No reporters are in the system yet.
    >>> Reporter.objects.all()
    <QuerySet []>

    # Create a new Reporter.
    >>> r = Reporter(full_name='John Smith')

    # Save the object into the database. You have to call save() explicitly.
    >>> r.save()

    # Now it has an ID.
    >>> r.id
    1

    # Now the new reporter is in the database.
    >>> Reporter.objects.all()
    <QuerySet [<Reporter: John Smith>]>

    # Fields are represented as attributes on the Python object.
    >>> r.full_name
    'John Smith'

    # Django provides a rich database lookup API.
    >>> Reporter.objects.get(id=1)
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__startswith='John')
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__contains='mith')
    <Reporter: John Smith>
    >>> Reporter.objects.get(id=2)
    Traceback (most recent call last):
        ...
    DoesNotExist: Reporter matching query does not exist.

    # Create an article.
    >>> from datetime import date
    >>> a = Article(pub_date=date.today(), headline='Django is cool',
    ...     content='Yeah.', reporter=r)
    >>> a.save()

    # Now the article is in the database.
    >>> Article.objects.all()
    <QuerySet [<Article: Django is cool>]>

    # Article objects get API access to related Reporter objects.
    >>> r = a.reporter
    >>> r.full_name
    'John Smith'

    # And vice versa: Reporter objects get API access to Article objects.
    >>> r.article_set.all()
    <QuerySet [<Article: Django is cool>]>

    # The API follows relationships as far as you need, performing efficient
    # JOINs for you behind the scenes.
    # This finds all articles by a reporter whose name starts with "John".
    >>> Article.objects.filter(reporter__full_name__startswith='John')
    <QuerySet [<Article: Django is cool>]>

    # Change an object by altering its attributes and calling save().
    >>> r.full_name = 'Billy Goat'
    >>> r.save()

    # Delete an object with delete().
    >>> r.delete()

## Une interface d’administration dynamique : ce n’est pas juste un échafaudage, c’est une vraie maison.

Une fois que vos modèles sont définis, Djando peut créer automatiquement une interface d’administration professionnelle et apte à la production, un site Web qui permet aux utilisateurs authentifiés d’ajouter, modifier et supprimer des objets. La seule exigence est d’inscrire votre modèle dans le site d’administration :

monsite/news/models.py

    from django.db import models

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

monsite/news/admin.py

    from django.contrib import admin

    from . import models

    admin.site.register(models.Article)

Ici, on part du principe que votre site peut être modifié par un membre du personnel, un client ou peut-être juste par vous, sans que vous deviez créer des interfaces d’administration uniquement pour gérer le contenu.

Un schéma habituel lors de la création d’une application Django est de créer les modèles et de mettre en place les sites d’administration aussi vite que possible, pour que votre équipe (ou clients) puisse commencer à saisir les données. Ensuite, le développement de la couche de présentation publique des données peut avancer à son rythme.

## Conception des URL

Un schéma d’URL propre et élégant est un aspect important dans une application Web de qualité. Django encourage la conception de belles URL et ne place aucune extension dans celles-ci, comme `.php` ou `.asp`.

Pour concevoir les URL d’une application, vous créez un module Python appelé URLconf. C’est un sommaire pour votre application, il contient les liaisons entre vos motifs d’URL et les fonctions Python associées. Ces configurations d’URL servent aussi à séparer les URL de votre code Python.

Voici à quoi peut ressembler un URLconf pour l’exemple de `Reporter`/`Article` précédent :

monsite/news/urls.py

    from django.urls import path

    from . import views

    urlpatterns = [
        path('articles/<int:year>/', views.year_archive),
        path('articles/<int:year>/<int:month>/', views.month_archive),
        path('articles/<int:year>/<int:month>/<int:pk>/', views.article_detail),
    ]

Le code ci-dessus relie des chemins d’URL aux fonctions Python réceptrices (« views »). Les chaînes de chemins utilisent des balises de paramètre pour « capturer » les valeurs à partir des URL. Quand un utilisateur demande une page, Django parcourt tous les chemins, dans l’ordre, et s’arrête dès qu’un de ces chemins correspond à l’URL demandée (si aucun d’eux ne correspond, Django appelle une vue 404 spéciale). Ceci est extrêmement rapide, car les chemins sont compilés en expressions régulières au chargement initial.

Dès qu’un des motifs d’URL correspond, Django appelle la vue associée, qui est une fonction Python. Chaque vue reçoit un objet requête (« request ») qui contient les métadonnées de la requête ainsi que les valeurs capturées dans le motif.

Par exemple, si un utilisateur demande l’URL « /articles/2005/05/39323/ », Django appellera la fonction `news.views.article_detail(request, year=2005, month=5, pk=39323)`.

## Écriture des vues

Chaque vue est responsable de faire une des deux choses suivantes : retourner un objet `HttpResponse` contenant le contenu de la page demandée, ou lever une exception, comme par exemple `Http404`. Le reste, c’est votre travail.

Généralement, une vue récupère des données d’après les paramètres, charge un template et affiche le template avec les données récupérées. Voici un exemple de vue pour l’exemple précédent `year_archive` :

monsite/news/views.py

    from django.shortcuts import render

    from .models import Article

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

Cet exemple utilise le système de gabarits de Django qui a plusieurs fonctions puissantes mais s’efforce de rester assez simple à l’utilisation pour les non-programmeurs.

## Élaboration de vos gabarits

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

L’algorithme de recherche des gabarits de Django vous permet de minimiser la redondance parmi les gabarits. Dans vos réglages de Django, vous indiquez une liste des dossiers contenant potentiellement des gabarits avec `DIRS`. Si un gabarit n’existe pas dans le premier dossier, Django vérifie le deuxième, etc.

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

monsite/news/templates/news/year_archive.html

    {% 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 deux accolades. `{{ article.headline }}` veut dire « Afficher la valeur de l’attribut titre de l’article ». Mais les points ne sont pas utilisés uniquement pour l’utilisation des attributs. Ils peuvent aussi être utilisés pour la recherche des clés de dictionnaires, d’index, ou pour appeler des fonctions.

Notez que `{{ article.pub_date|date:"F j, Y" }}` utilise des « tuyaux » de type Unix (le caractère «|» (pipe)). On appelle cela un filtre de gabarit, c’est un moyen de filtrer la valeur d’une variable. Dans le cas présent, le filtre « date » formate un objet Python de type « datetime » dans le format fourni (comme dans la fonction « date » de PHP).

Vous pouvez enchaîner autant de filtres que vous le voulez. Vous pouvez écrire vos propres filtres de gabarits. Vous pouvez écrire des balises de gabarits personnalisées qui utilisent du code Python en arrière-plan.

Enfin, Django utilise le concept d”« héritage de gabarits ». C’est ce que fait `{% extends "base.html" %}`. Cela veut dire « Charge premièrement le gabarit nommé “base”, qui a défini certains blocs, et remplit ces blocs avec le contenu qui suit. ». Pour résumer, cela permet de diminuer significativement la redondance dans les gabarits : chaque gabarit ne doit définir que ce qui lui est propre.

Voici à quoi le gabarit « base.html » pourrait ressembler, y compris l’utilisation de fichiers statiques :

monsite/templates/base.html

    {% load static %}
    <html>
    <head>
        <title>{% block title %}{% endblock %}</title>
    </head>
    <body>
        <img src="{% static 'images/sitelogo.png' %}" alt="Logo">
        {% block content %}{% endblock %}
    </body>
    </html>

De façon simplifiée, il définit l’aspect général de votre site (avec le logo) et positionne des « trous » que les gabarits enfants peuvent remplir. De cette façon, le changement de style d’un site revient à modifier un seul fichier, le gabarit de base.

Cela vous permet aussi de créer plusieurs versions d’un site, avec des gabarits de base différents, tout en réutilisant les gabarits enfants. Les créateurs de Django ont utilisé cette technique pour créer des versions « mobiles » très différentes de leurs sites, en créant simplement un nouveau gabarit de base.

Notez que vous n’avez pas à utiliser le système de gabarits de Django si vous en préférez un autre. Bien que le système de gabarits de Django soit particulièrement bien intégré avec la couche modèle de Django, rien ne vous force à l’utiliser. Vous n’êtes pas non plus obligé d’utiliser l’API de base de données de Django. Il est possible d’utiliser une autre couche d’abstraction de base de données, de lire des fichiers XML, des fichiers sur le disque ou toute autre solution. Chaque partie de Django — modèles, vues, gabarits — est découplée des autres.

## Ceci n’est que la base

Ceci n’était qu’un rapide coup d’œil sur les fonctions de Django. En voici quelques autres utiles :

- Un système de cache qui s’intègre avec « memcached » ou d’autres moteurs.
- Un système de syndication qui permet de créer des flux RSS et Atom en écrivant une petite classe Python.
- D’autres sympatiques fonctionnalités automatiquement générées pour l’interface d’administration, cet aperçu a tout juste effleuré la surface.

Pour vous, les étapes suivantes sont de télécharger Django, de lire le didacticiel et de rejoindre la communauté. Merci de votre intérêt !