L’application flatpages (pages statiques)¶
Django est livré avec une application « flatpages » facultative. Elle permet de stocker du contenu HTML simple « à 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 simple 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é.
Voici quelques exemples de flatpages sur des sites motorisés par Django :
Installation¶
Pour installer l’application flatpages, procédez comme suit :
Installez le
gestionnaire de sites
en ajoutant'django.contrib.sites'
à votre réglageINSTALLED_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éralement1
(c’est-à-direSITE_ID = 1
, mais si vous utilisez le gestionnaire de sites pour gérer plusieurs sites, ce pourrait être l’identifiant d’un autre site.Ajoutez
'django.contrib.flatpages'
au réglageINSTALLED_APPS
.
Puis, au choix :
Ajoutez une entrée dans votre configuration d’URL. Par exemple :
urlpatterns = [ path('pages/', include('django.contrib.flatpages.urls')), ]
ou :
- Ajoutez
'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'
au réglageMIDDLEWARE
. - 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 simple qui associe simplement une URL à un titre et un champ de contenu textuel. django_flatpage_sites
associe une flatpage à un site.
Utilisation de la configuration d’URL¶
Il y a plusieurs façons d’inclure les pages statiques dans la configuration d’URL. Vous pouvez dédier un chemin particulier pour les pages statiques :
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 += [
path('<path: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.
Une autre configuration courante consiste à utiliser des pages statiques pour un nombre limité de pages connues à l’avance et à figer leurs URL, afin de pouvoir y faire référence avec la balise de gabarit url
:
from django.contrib.flatpages import views
urlpatterns += [
path('about-us/', views.flatpage, {'url': '/about-us/'}, name='about'),
path('license/', views.flatpage, {'url': '/license/'}, name='license'),
]
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 utiliseRequestContext
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.
- Si la flatpage a un gabarit personnalisé, il charge ce gabarit. Sinon, il charge le gabarit
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
Notez que FlatpageFallbackMiddleware
n’entre en jeu qu’une fois qu’une autre vue a réussi à produire une réponse 404. Si une autre vue ou une autre classe d’intergiciel tente de produire une réponse 404 mais finit par générer une exception à la place, la réponse devient HTTP 500 (« Erreur interne du serveur ») et FlatpageFallbackMiddleware
ne tentera pas de servir une page statique.
Comment ajouter, modifier et supprimer des flatpages¶
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¶
-
class
FlatPage
¶ Les flatpages sont représentées par un modèle Django standard défini dans django/contrib/flatpages/models.py. 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.
Gabarits de flatpage¶
Par défaut, les flatpages sont rendues par le gabarit flatpages/default.html
, mais vous pouvez le remplacer pour une flatpage donnée : dans l’interface d’administration, une section refermée et intitulée « Options avancées » (un clic l’ouvrira) contient un champ pour définir un nom de gabarit. Si vous créez une page statique via l’API Python, vous pouvez simplement définir le nom du gabarit via le champ template_name
de l’objet FlatPage
.
La création du gabarit flatpages/default.html
est de votre responsabilité ; dans votre répertoire de gabarits, il suffit de créer 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>
<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)¶
By default, the get_flatpages
template tag will only show
flatpages that are marked registration_required = False
. If you
want to display registration-protected flatpages, you need to specify
an authenticated user using a for
clause.
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
[source]¶ La classe
sitemaps.FlatPageSitemap
regarde toutes lesflatpages
publiquement visibles définies pour leSITE_ID
courant (voir ladocumentation des « sites »
) et crée une entrée dans le plan du site. Ces entrées incluent uniquement l’attributlocation
– et paslastmod
,changefreq
oupriority
.
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'),
]