# Documentation Django 5.2.8

# L’application flatpages (pages statiques)

Django est livré avec une application « flatpages » facultative. Elle permet de stocker du contenu HTML « à plat » dans la base de données et d’en assurer la gestion pour vous via l’interface d’administration de Django et une API Python.

Une flatpage (littéralement « page plate ») est un objet avec une URL, un titre et un contenu. Ces pages sont utiles pour des pages spéciales à usage unique, telles que les pages « À propos » ou « Politique de confidentialité » que vous souhaitez stocker dans une base de données mais pour lesquelles vous ne voulez pas développer une application Django dédiée.

Une flatpage peut utiliser un gabarit personnalisé ou un gabarit de flatpage par défaut pour l’ensemble du système. Elle peut être associés à un ou plusieurs sites.

Le champ de contenu peut éventuellement être laissé vierge si vous préférez placer le contenu dans un gabarit personnalisé.

## Installation

Pour installer l’application flatpages, procédez comme suit :

1. Installez le `gestionnaire de sites` en ajoutant `'django.contrib.sites'` à votre réglage `INSTALLED_APPS`, si ce n’est déjà fait.

   Assurez-vous également d’avoir correctement configuré `SITE_ID` avec l’identifiant du site que le fichier de réglages représente. C’est généralement `1` (c’est-à-dire `SITE_ID = 1`), mais si vous utilisez le gestionnaire de sites pour gérer plusieurs sites, ce pourrait être l’identifiant d’un autre site.

2. Ajoutez `'django.contrib.flatpages'` au réglage `INSTALLED_APPS`.

Puis, au choix :

3. Ajoutez une entrée dans votre configuration d’URL. Par exemple :

       urlpatterns = [
           path("pages/", include("django.contrib.flatpages.urls")),
       ]

ou :

3. Ajoutez `'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'` au réglage `MIDDLEWARE`.

4. Lancez la commande `manage.py migrate`.

## Fonctionnement

`manage.py migrate` crée deux tables dans votre base de données : `django_flatpage` et `django_flatpage_sites`. `django_flatpage` est une table de correspondance qui associe une URL à un titre et un champ de contenu textuel. `django_flatpage_sites` associe une flatpage à un site.

### Utilisation de la configuration d’URL

There are several ways to include the flatpages in your URLconf. You can dedicate a particular path to flatpages:

    urlpatterns = [
        path("pages/", include("django.contrib.flatpages.urls")),
    ]

Vous pouvez également le configurer comme un motif « fourre-tout ». Dans ce cas, il est important de placer le motif à la fin des autres `urlpatterns`:

    from django.contrib.flatpages import views

    # Your other patterns here
    urlpatterns += [
        re_path(r"^(?P<url>.*/)$", views.flatpage),
    ]

Avertissement

Si vous définissez `APPEND_SLASH` à `False`, vous devez supprimer la barre oblique dans le motif fourre-tout, sinon les flatpages sans barre oblique finale ne seront pas identifiées.

Another common setup is to use flatpages for a limited set of known pages and to hardcode their URLs in the URLconf:

    from django.contrib.flatpages import views

    urlpatterns += [
        path("about-us/", views.flatpage, kwargs={"url": "/about-us/"}, name="about"),
        path("license/", views.flatpage, kwargs={"url": "/license/"}, name="license"),
    ]

L’argument `kwargs` définit la valeur `url` utilisée pour la requête de modèle `FlatPage` dans la vue `flatpage`.

L’argument `name` permet à l’URL d’être résolue dans les gabarits, par exemple en utilisant la balise de gabarit `url`.

### Utilisation de l’intergiciel

L’intergiciel `FlatpageFallbackMiddleware` peut se charger de tout le travail.

class FlatpageFallbackMiddleware

  Chaque fois qu’une application Django génère une erreur 404, cet intergiciel vérifie si la base de données flatpages contient l’URL demandée en dernier recours. Plus précisément, il recherche une flatpage avec l’URL donnée et avec un identifiant de site qui correspond au réglage `SITE_ID`.

  S’il trouve une correspondance, il suit cet algorithme :

  - Si la flatpage a un gabarit personnalisé, il charge ce gabarit. Sinon, il charge le gabarit `flatpages/default.html`.

  - Il transmet à ce gabarit une variable unique de contexte, `flatpage`, qui est l’objet flatpage. Il utilise `RequestContext` dans le rendu du gabarit.

  L’intergiciel ne fera qu’ajouter une barre oblique finale et rediriger (en fonction du réglage `APPEND_SLASH`) si l’URL résultante se réfère à une flatpage valide. Les redirections sont permanentes (code 301).

  Si aucune correspondance n’est trouvée, le traitement de la requête continue normalement.

  L’intergiciel ne s’active que pour les erreurs 404 – pas pour les erreurs 500 ni les réponses ayant un autre code de statut.

Les flatpages n’appliquent pas d’intergiciel de vue

Comme l’intergiciel `FlatpageFallbackMiddleware` n’est appliqué qu’après l’échec de la résolution de l’URL et la production d’une erreur 404, la réponse qu’il renvoie n’applique aucune des méthodes d’intergiciel de vue. Seules les requêtes qui sont routées avec succès vers une vue par la résolution normale de l’URL appliquent les intergiciels de vue.

Notez que l’ordre de `MIDDLEWARE` est important. Généralement, vous pouvez mettre `FlatpageFallbackMiddleware` à la fin de la liste. Cela signifie qu’il s’exécutera en premier lors du traitement de la réponse et garantira que tout autre intergiciel qui traite la réponse voit la réponse de la flatpage plutôt que la 404.

Pour plus d’informations sur cet intergiciel, lisez la documentation des intergiciels.

Le gabarit 404 doit fonctionner

Note that the `FlatpageFallbackMiddleware` only steps in once another view has successfully produced a 404 response. If another view or middleware class attempts to produce a 404 but ends up raising an exception instead, the response will become an HTTP 500 (« Internal Server Error ») and the `FlatpageFallbackMiddleware` will not attempt to serve a flatpage.

## Comment ajouter, modifier et supprimer des flatpages

Avertissement

Les permissions d’ajouter et de modifier des pages «flatpages» devraient être restreintes à des utilisateurs de confiance. Le contenu de ces pages est en HTML brut et n’est pas contrôlé par Django. Par conséquent, une de ces pages au contenu malveillant peut conduire à diverses vulnérabilités de sécurité, y compris l’escalade de permissions.

### Via l’interface d’administration

Si vous avez activé l’interface d’administration automatique de Django, vous devriez voir une section « Flatpages » sur la page d’accueil de l’administration. Les flatpages sont éditables comme pour n’importe quel autre objet du système.

Le modèle `FlatPage` possède un champ `enable_comments` qui n’est pas exploité par `contrib.flatpages`, mais il pourrait être utile pour votre projet ou des applications tierces. Il n’apparaît pas dans l’interface d’administration, mais vous pouvez l’ajouter en inscrivant un `ModelAdmin` personnalisé pour `FlatPage`:

    from django.contrib import admin
    from django.contrib.flatpages.admin import FlatPageAdmin
    from django.contrib.flatpages.models import FlatPage
    from django.utils.translation import gettext_lazy as _

    # Define a new FlatPageAdmin
    class FlatPageAdmin(FlatPageAdmin):
        fieldsets = [
            (None, {"fields": ["url", "title", "content", "sites"]}),
            (
                _("Advanced options"),
                {
                    "classes": ["collapse"],
                    "fields": [
                        "enable_comments",
                        "registration_required",
                        "template_name",
                    ],
                },
            ),
        ]

    # Re-register FlatPageAdmin
    admin.site.unregister(FlatPage)
    admin.site.register(FlatPage, FlatPageAdmin)

### Via l’API Python

Les flatpages sont représentées par un modèle Django standard, `FlatPage`. Vous pouvez accéder aux objets flatpage via l’API de base de données de Django.

Éviter les doublons d’URL de flatpages

Si vous ajoutez ou modifiez les flatpages via votre propre code, il est souhaitable d’éviter des URL définies en double pour un même site. Le formulaire de flatpage utilisé dans l’interface d’administration effectue ce contrôle de validation et peut être importé depuis `django.contrib.flatpages.forms.FlatpageForm` et être utilisé dans vos propres vues.

## Le modèle `FlatPage`

class models.FlatPage

### Champs

Les objets `FlatPage` possèdent les champs suivants :

class models.FlatPage
  url

    Obligatoire. 100 caractères au maximum. Indexé pour des recherches plus rapides.

  title

    Obligatoire. 200 caractères au maximum.

  content

    Facultatif (`blank=True`). Un champ `TextField` qui contient typiquement le contenu HTML de la page.

  enable_comments

    Booléen. Ce champ n’est pas utilisé par `flatpages` par défaut et n’apparaît pas dans l’interface d’administration. Veuillez consulter la section sur l’interface d’administration de flatpages pour une explication détaillée.

  template_name

    Facultatif (`blank=True`). Au maximum 70 caractères. Indique le gabarit utilisé pour produire la page. Si non défini, c’est le gabarit `flatpages/default.html` qui est utilisé.

  sites

    Relation plusieurs-à-plusieurs vers `Site`, ce qui détermine sur quels sites cette page statique sera disponible.

### Méthodes

class models.FlatPage
  get_absolute_url()

    Renvoie le chemin d’URL relatif vers la page, basé sur l’attribut `url`.

## Gabarits de flatpage

By default, flatpages are rendered via the template `flatpages/default.html`, but you can override that for a particular flatpage: in the admin, a collapsed fieldset titled « Advanced options » (clicking will expand it) contains a field for specifying a template name. If you’re creating a flatpage via the Python API you can set the template name as the field `template_name` on the `FlatPage` object.

La création du gabarit `flatpages/default.html` est de votre responsabilité ; dans votre répertoire de gabarits, créez un répertoire `flatpages` contenant un fichier `default.html`.

Les gabarits de flatpage ne reçoivent qu’une seule variable de contexte, `flatpage`, qui correspond à l’objet flatpage.

Voici un exemple de gabarit `flatpages/default.html`:

    <!DOCTYPE html>
    <html lang="en">
    <head>
    <title>{{ flatpage.title }}</title>
    </head>
    <body>
    {{ flatpage.content }}
    </body>
    </html>

Puisqu’il est possible de saisir du contenu HTML brut dans la page d’administration d’une flatpage, `flatpage.title` et `flatpage.content` sont tous deux marqués comme ne requérant pas d’échappement HTML automatique dans le gabarit.

## Obtention d’une liste d’objets `FlatPage` dans un gabarit

L’application flatpages fournit une balise de gabarit permettant de parcourir l’ensemble des flatpages disponibles pour le site actuel.

Comme pour toute balise de gabarit personnalisée, il est nécessaire de charger sa bibliothèque de balises personnalisées avant de pouvoir l’utiliser. Après le chargement de la bibliothèque, vous pouvez récupérer toutes les flatpages actuelles via la balise `get_flatpages`:

    {% load flatpages %}
    {% get_flatpages as flatpages %}
    <ul>
        {% for page in flatpages %}
            <li><a href="{{ page.url }}">{{ page.title }}</a></li>
        {% endfor %}
    </ul>

### Affichage des flatpages avec `registration_required` (connexion requise)

Par défaut, la balise de gabarit `get_flatpages` n’affiche que les flatpages dont le champ `registration_required = False`. Si vous souhaitez afficher les flatpages limitées aux utilisateurs connectés, vous devez indiquer un utilisateur authentifié en utilisant une clause `for`.

Par exemple :

    {% get_flatpages for someuser as about_pages %}

Si vous indiquez un utilisateur anonyme, `get_flatpages` se comporte comme si vous n’aviez pas indiqué d’utilisateur, c’est-à-dire qu’elle ne montre que les flatpages publiques.

### Filtrage des flatpages selon une URL de base

Un paramètre facultatif, `starts_with`, peut être appliqué pour limiter les pages affichées à celles qui commencent par une URL de base particulière. Ce paramètre peut être transmis sous forme de chaîne ou comme variable à résoudre par le contexte.

Par exemple :

    {% get_flatpages '/about/' as about_pages %}
    {% get_flatpages about_prefix as about_pages %}
    {% get_flatpages '/about/' for someuser as about_pages %}

## Intégration avec `django.contrib.sitemaps`

class FlatPageSitemap

  La classe `sitemaps.FlatPageSitemap` regarde toutes les `flatpages` publiquement visibles définies pour le `SITE_ID` courant (voir la `documentation des « sites »`) et crée une entrée dans le plan du site. Ces entrées incluent uniquement l’attribut `location` – et pas `lastmod`, `changefreq` ou `priority`.

### Exemple

Voici un exemple de configuration d’URL utilisant `FlatPageSitemap`:

    from django.contrib.flatpages.sitemaps import FlatPageSitemap
    from django.contrib.sitemaps.views import sitemap
    from django.urls import path

    urlpatterns = [
        # ...
        # the sitemap
        path(
            "sitemap.xml",
            sitemap,
            {"sitemaps": {"flatpages": FlatPageSitemap}},
            name="django.contrib.sitemaps.views.sitemap",
        ),
    ]