Créer des thèmes

Tout ce que vous écrivez dans FolioPress — pages, articles, étiquettes — vit à part de la façon dont c’est affiché. Cette couche de présentation est un thème, et ce guide en démonte un : le dossier, les gabarits, le fichier de réglages et exactement quelles données chaque gabarit reçoit. Si vous êtes à l’aise avec HTML et CSS, vous avez tout ce qu’il faut.

Un thème est un dossier

Changez de thème et les mêmes pages, articles et menu sont redessinés — rien dans le contenu ne change, seulement sa tenue. Un thème est un dossier contenant trois choses : un fichier de réglages, des gabarits et des ressources statiques.

Quatre gabarits sont obligatoires — base.html, home.html, page.html et post.html — et un thème qui en manque ne se charge pas. Tout le reste est facultatif : une archive d’étiquette, une page de recherche, des pages d’erreur personnalisées, une mise en page dédiée à une page précise, et un dossier locales/ pour les mots du thème lui-même. Les thèmes se modifient directement dans l’administration, sous Thèmes, s’exportent en zip et s’importent sur un autre site.

D’une URL à une page

Il est utile de voir ce que FolioPress fait d’une requête avant même que votre gabarit ne s’exécute, car cela explique pourquoi les gabarits sont si courts.

Deux choses à retenir. La langue est lue dans le préfixe de l’URL, si bien que /fr-fr/a-propos et /about sont la même page en deux langues, et le contexte remis à votre gabarit est déjà dans la bonne — chaque titre, slug, libellé de menu et contenu. Et le gabarit est choisi pour vous : pour une page dont le slug en langue principale est about, FolioPress cherche d’abord page-about.html et se rabat sur page.html. Il n’y a rien à câbler.

Un squelette, plusieurs pages

Les gabarits sont du Jinja2 — du HTML avec deux sortes d’accolades en plus. {{ page.title }} affiche une valeur. {% if page.poster_image_url %} … {% endif %} est une instruction : boucles, conditions et héritage.

base.html contient tout ce que les pages ont en commun — le <head>, la navigation, le sélecteur de langue, le pied de page, les scripts — avec un seul emplacement vide au milieu. Tous les autres gabarits commencent de la même façon et remplissent cet emplacement :

{% extends "base.html" %}

{% block content %}
  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}
{% endblock %}

Tout ce qui se répète d’un gabarit à l’autre — une carte d’article, une barre de pagination — va dans partials/ et s’inclut avec {% include "partials/post-card.html" %}.

theme.yml : le panneau de réglages

C’est ici qu’un thème se décrit et configure quelques comportements, sans toucher à un gabarit. Voici ce qu’utilisent les thèmes fournis :

title: "Ink"
description: "Un thème sobre et minimaliste"
version: "1.0.0"
author: "FolioPress"

meta:
  supports_dark_mode: true
  responsive: true
  categories: [minimal, portfolio]

settings:                    # libre ; disponible dans les gabarits sous theme_settings
  primary_color: "#2563eb"

home:
  posts: 10                  # combien d’articles la page d’accueil reçoit
  order_by: "-published_at"  # les plus récents d’abord
  has_pagination: false      # une coupure, ou de vrais liens de page ?
  image_ratios:
    poster: "16:9"           # ce que propose l’outil de recadrage de l’administration ici
    gallery: "free"

page:  { posts: 10, order_by: "-published_at", has_pagination: false }
post:  { posts: 3,  order_by: "-published_at" }   # articles liés sous un article
tag:   { posts: 12, order_by: "-published_at", has_pagination: true }

page-about:                  # surcharge pour une page, par son slug en langue principale
  image_ratios: { poster: "1:1" }
post-tutorials:              # surcharge pour les articles dont la première étiquette a ce slug
  image_ratios: { poster: "4:3" }

Ce que chaque gabarit peut voir

Un gabarit ne va jamais rien chercher. On lui remet un ensemble de valeurs prêtes à l’emploi — FolioPress l’appelle le contexte — et il affiche ce dont il a besoin. Une partie de l’ensemble est identique sur chaque page ; le reste dépend du gabarit en cours de rendu.

Commun à tous les gabarits

L’objet page

La même forme, qu’il s’agisse d’une page, d’un article ou d’un élément de n’importe quelle liste d’articles :

Listes d’articles

Chaque liste d’articles est accompagnée d’une pagination de même forme : has_pagination, current_page, total_pages, has_previous, has_next, previous_page, next_page, et pagination_urls avec first, previous, next et last — None là où il n’y a nulle part où aller. Avec `has_pagination` désactivé dans `theme.yml`, la liste est simplement coupée à `posts` et les indicateurs restent à faux.

Les langues et le sélecteur

Deux des champs de langue sont calculés pour vous. short_code est le code de langue seul — EN — sauf si le site active aussi une autre variante de la même langue, auquel cas il garde sa région : EN-US et EN-GB. menu_label suit la même règle avec les noms : English, ou English (US) et English (UK). C’est exactement la règle qu’utilise le sélecteur de langue de l’administration elle-même, si bien que le site et l’administration ne se contredisent jamais sur un libellé. Un sélecteur complet est donc court :

{% if languages | length > 1 %}
<button type="button" aria-label="{{ t('Change language') }}">
  {{ current_language.short_code }}
</button>
<ul>
  {% for lang in languages.values() | sort(attribute='menu_label') %}
  <li>
    {% if lang.code == current_language.code %}
      <span aria-current="true">{{ lang.menu_label }}</span>
    {% else %}
      <a href="{{ language_switch_urls[lang.code] }}" hreflang="{{ lang.code }}">{{ lang.menu_label }}</a>
    {% endif %}
  </li>
  {% endfor %}
</ul>
{% endif %}

language_switch_urls pointe déjà vers la même page dans chaque langue — le slug traduit, ou la page d’accueil si cette traduction n’existe pas encore —, de sorte qu’un sélecteur ne construit jamais d’URL lui-même.

Les mots du thème lui-même

Le contenu est traduit par l’auteur dans l’administration. Les mots propres au thème — « Lire la suite », « Rechercher », « Tous droits réservés » — sont traduits par le thème, dans templates/locales/<langue>.json :

{
  "Read more": "Lire la suite",
  "Search": "Rechercher",
  "Change language": "Changer de langue"
}

Entourez la phrase de {{ t('Read more') }} et elle s’affiche dans la langue du visiteur. Une phrase absente du fichier de cette langue se rabat sur le fichier de la langue principale, puis sur la phrase elle-même — un thème à moitié traduit fonctionne donc toujours, simplement en anglais là où la traduction n’a pas encore été écrite. Les fichiers voyagent avec le thème lors de l’export.

Une page, sa propre mise en page

Une page d’atterrissage, un formulaire de contact, une grille de portfolio — parfois une page mérite une mise en page dont aucune autre n’a besoin. Ajoutez un gabarit nommé page-<slug>.html, où <slug> est le slug de cette page dans la langue principale, et FolioPress l’utilise pour cette page dans toutes les langues. Supprimez le fichier et la page revient discrètement à page.html.

{# templates/page-about.html #}
{% extends "base.html" %}
{% block content %}
<section class="about">
  <img src="{{ page.poster_image_url }}" alt="">
  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}
</section>
{% endblock %}

La page qu’un administrateur désigne comme page du formulaire de contact reçoit un petit supplément : is_contact_page est vrai, contact_form_action indique où le formulaire doit envoyer, et contact_guard_token / contact_honeypot_field sont deux champs cachés qui tiennent les robots à l’écart. Après un envoi, contact_status vous dit s’il faut afficher un remerciement ou une erreur.

Partez d’un thème qui fonctionne

Le moyen le plus rapide de construire un thème est d’ouvrir l’un des thèmes fournis — chacun a une démonstration en direct — et de le lire à côté de cette page. Dupliquez-le dans l’administration, modifiez le CSS, puis les gabarits, et vous aurez quelque chose à vous sans jamais être parti d’un fichier vide.