Variables & Helpers de Template

Les thèmes reçoivent leurs données comme un ensemble plat de valeurs : le builder calcule tout (URLs, dates, menus, design tokens, fragments rendus) avant que votre template ne tourne, puis vous remet les résultats comme variables simples. Cette page liste ce qui est disponible et comment fonctionnent les « helpers ». (Pour les variables essentielles et la syntaxe, la référence Template couvre les cas de base ; cette page approfondit.)

Comment fonctionnent les helpers dans Chinaski

Il n'y a aucune fonction de template personnalisée à apprendre : la syntaxe standard de Template Toolkit est tout ce qu'il y a ([% variable %], filtres comme | html et | uri, IF/FOREACH/INCLUDE, etc.). Les « helpers » en pratique sont des variables pré-calculées : au lieu de vous demander de formater des dates ou d'assembler des URLs dans le code de template, le builder les calcule et passe la réponse. Les pièges connus découlent de ceci : il n'y a pas d'objets à la page.title (utilisez title), et les dates arrivent prêtes à l'emploi (utilisez la variable date pré-calculée).

Les variables de base (par type de contenu)

Les tables de la référence Template restent le contrat primaire pour page.tt/post.tt/blog_index.tt/search.tt, title, body (pré-rendu, n'échappez pas), slug, lang, canonical_url, nav_items, champs d'image mise en avant, IDs d'analytique, password_hash, liens hreflang, breadcrumbs, etc. Cette page documente tout le reste réellement fourni.

Variables de niveau site que chaque vue reçoit

site_name, site_tagline, footer_copyright, year, url_base: identité et racines d'URL.
blog_prefix, blog_url_base: le préfixe de chemin du blog dans la langue courante, et l'adresse racine du blog, pré-construits.
dir: 'ltr' ou 'rtl' par langue ; utilisez-le sur <html> pour que les langues de droite à gauche fonctionnent.
Contacts de footer: org_phone, org_email, org_linkedin, org_instagram provenant des réglages du site.
footer_feed_url: l'adresse du flux (vide quand le site n'a pas de posts publiés).
Variables de cookie-notice: le texte de la notice, le lien de politique et les labels de bouton, chacun se résolvant à une surcharge par langue quand il en existe une.
noindex, airgap: booléens simples ; un theme peut changer de comportement (p. ex. ignorer les scripts de partage) quand l'un est vrai.
Variables PWA: pwa_enabled, pwa_theme_color, pwa_short_name.

nav_items: la liste plate par slot (label/url/slot/sort), incluant les liens externes.
nav_by_slot et nav_tree_by_slot: les mêmes éléments groupés par slot ('header'/'footer'), et de surcroît des arbres parent/enfant pré-construits pour les menus imbriqués : vous n'assemblez pas l'imbrication vous-même.

Fragments pré-rendus

Certains fragments de HTML sont assemblés avant que votre template ne tourne et vous parviennent déjà rendus :

sidebar_html: la sortie du partial sidebar (rendu quand votre thème fournit _sidebar.tt ; la config du theme peut désactiver la sidebar).
stacks_html: chaque stack affecté à cette page/post, rendus dans l'ordre.
area_html: une carte nom d'aire → blocks rendus pour les thèmes qui utilisent des aires de layout ; rendez le HTML de chaque aire au point du template où cette aire appartient.

Configuration et tokens

theme_config: un theme peut porter ses propres réglages clé/valeur (stockés dans la base de données avec le theme) et les lire dans les templates.
design_tokens: la liste des design tokens du site ; la plupart des thèmes utilisent les tokens via le CSS généré, mais la liste est fournie pour les cas avancés.
custom_fields: les champs clé/valeur personnalisés de cette fiche.
page_authors / post_authors: la liste des auteurs affectés.
children (pages) : les sous-pages sous cette page, prêtes pour du listing ou des menus.
default_site_image (+ une variante absolue) : l'image de partage de repli du site ; favicon_enabled, logo_file: le drapeau du pipeline favicon et le fichier logo configuré.
Variantes d'images absolues: les variables d'image mise en avant et d'image OG viennent avec des formes en URL absolue déjà résolues, de sorte que les tags sociaux ne construisent pas d'URLs eux-mêmes.

Ce qui se passe après la sortie de votre template

Le HTML de votre template est achevé par le builder : les snippets sont injectés dans le head/body où configurés, et le résultat est minifié par défaut (un réglage peut désactiver cela) avant d'être écrit sur le disque.

L'idée de theme-config

Un theme peut définir ses propres réglages (theme_config) : le builder les charge depuis la base de données et les passe à chaque rendu. Combiné au répertoire de thème à repli par défaut (votre thème n'a besoin que des templates qu'il change ; les fichiers manquants retombent sur les intégrés), votre theme reste simple.

La version courte

Variables en = réponses en sortie : le builder fait le calcul pour que les templates restent déclaratifs, des noms plats, des valeurs correctes et localisées, pas de code de formatage, pas de fonctions personnalisées. Si une valeur dont vous avez besoin n'y figure pas (état par visite, méta par fiche), elle est généralement joignable via custom_fields, les design tokens, ou les variables dérivées des réglages du site listées plus haut.