Organisation des fichiers

Types de templates

Il existe trois types de templates, layouts, components et autres templates : layouts sont utilisés pour afficher les pages, et chacun d'eux peut inclure des templates et components.

Convention de nommage

Les fichiers templates sont stockés dans le répertoire layouts/ et doivent être nommés selon la convention suivante :

layouts/(<section>/)<type>|<layout>.<format>(.<language>).twig

<section> (facultatif)

La section de la page (ex. : blog).

<type>

Le type de page : home (ou index) pour homepage, list pour list, page pour page, etc. (Voir Règles de recherche pour plus de détails).

<layout> (facultatif)

Le nom de la layout personnalisée défini dans le front-matter de la page (par exemple : layout: my-layout).

<format>

Le format de sortie de la page rendue (par exemple : html, rss, json, xml, etc.).

<language> (facultatif)

La langue de la page (ex. : fr).

Exemples :

layouts/home.html.twig       # `type` est "homepage"
layouts/page.html.twig       # `type` est "page"
layouts/page.html.fr.twig    # `type` est "page" et `language` est "fr"
layouts/my-layout.html.twig  # `layout` est "my-layout"
layouts/blog/list.html.twig  # `section` est "blog"
layouts/blog/list.rss.twig   # `section` est "blog" et `format` est "rss"

<mon-site>
├─ ...
├─ layouts
|  ├─ index.html.twig      # Utilisé par le type "homepage"
|  ├─ list.html.twig       # Utilisé par les types "homepage" et "section"
|  ├─ list.rss.twig        # Utilisé par les types "homepage" et "section", pour le format de sortie RSS
|  ├─ page.html.twig       # Utilisé par le type "page"
|  ├─ taxonomy
|  |  ├─ tags.html.twig    # Utilisé par le type "vocabulary" de `tags` (liste des termes)
|  |  └─ tag.html.twig     # Utilisé par le type "term" de `tags` (liste des pages)
|  ├─ my-layout.html.twig  # Utilisé par les pages avec `layout: my-layout` dans le front-matter
|  ├─ ...
|  └─ partials
|     ├─ footer.html.twig  # Template inclus
|     └─ ...
└─ themes                  # Layouts et templates des thèmes
   └─ ...

Templates intégrés

Cecil est livré avec un ensemble de templates intégrés.

Règles de recherche

Dans la plupart des cas vous n'avez pas besoin de préciser la layout : Cecil sélectionne la layout la plus appropriée, en fonction du type de la page.

Par exemple, la sortie HTML de home page (index.md) sera rendue :

1. avec my-layout.html.twig si la variable layout est définie sur "my-layout" (dans le préambule)
2. sinon, avec index.html.twig si le fichier existe
3. sinon, avec home.html.twig si le fichier existe
4. sinon, avec list.html.twig si le fichier existe

Toutes les règles sont détaillées ci-dessous, pour chaque type de page, par ordre de priorité.

Type homepage

1. <layout>.<format>.twig
2. index.<format>.twig
3. home.<format>.twig
4. list.<format>.twig
5. _default/<layout>.<format>.twig
6. _default/index.<format>.twig
7. _default/home.<format>.twig
8. _default/list.<format>.twig
9. _default/page.<format>.twig

Type page

1. <section>/<layout>.<format>.twig
2. <layout>.<format>.twig
3. <section>/page.<format>.twig
4. _default/<layout>.<format>.twig
5. page.<format>.twig
6. _default/page.<format>.twig

Type section

1. <layout>.<format>.twig
2. <section>/index.<format>.twig
3. <section>/list.<format>.twig
4. section/<section>.<format>.twig
5. <parent>/index.<format>.twig, <parent>/list.<format>.twig et section/<parent>.<format>.twig, pour chaque section parente d’une sous-section (la plus proche en premier)
6. _default/section.<format>.twig
7. list.<format>.twig
8. _default/list.<format>.twig

Type vocabulary

1. taxonomy/<plural>.<format>.twig
2. vocabulary.<format>.twig
3. _default/vocabulary.<format>.twig

Type term

1. taxonomy/<plural>/<term>.<format>.twig
2. taxonomy/<singular>.<format>.twig
3. term.<format>.twig
4. _default/term.<format>.twig
5. _default/list.<format>.twig

Fonctions peut être appelée pour générer du contenu. Les fonctions sont appelées par leur nom suivi de parenthèses (()) et peuvent avoir des arguments.

url

Crée une URL valide pour une page, une entrée de menu, un actif, un ID de page ou un chemin.

{{ url(value, {options}) }}

Exemples :

{# page #}
{{ url(page) }}
{{ url(page, {canonical: true}) }}
{{ url(page, {format: json}) }}
{{ url(page, {language: fr}) }}
{# menu entry #}
{{ url(site.menus.main.about) }}
{# asset #}
{{ url(asset('styles.css')) }}
{# page ID #}
{{ url('page-id') }}
{# path #}
{{ url('about-me/') }}
{{ url('tags/' ~ tag) }}

html

Crée un élément HTML à partir d'un actif (ou d'un tableau d'actifs avec des attributs personnalisés).

{{ html(asset, {attributes}, {options}) }}
{# dedicated functions for each common type of asset #}
{{ css(asset) }}
{{ js(asset) }}
{{ image(asset) }}
{{ audio(asset) }}
{{ video(asset) }}

Exemples :

{# CSS with an attribute #}
{{ html(asset('print.css'), {media: 'print'}) }}
{# CSS with an attribute and an option #}
{{ html(asset('styles.css'), {title: 'Main theme'}, {preload: true}) }}
{# Array of assets with media query #}
{{ html([
  {asset: asset('css/style.css')},
  {asset: asset('css/style-dark.css'), attributes: {media: '(prefers-color-scheme: dark)'}}
]) }}
{# JavaScript #}
{{ html(asset('script.js')) }}
{# image without specific attributes nor options #}
{{ html(asset('image.png')) }}
{# image with specific attributes, responsive images and alternative formats #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {responsive: true, formats: ['avif', 'webp']}) }}
{# image with responsive pixels density images #}
{{ html(asset('image.jpg'), options={responsive: 'density'}, attributes={width: 256}) }}
{# image with a Low-Quality Image Placeholder #}
{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {placeholder: 'lqip'}) }}
{# Audio #}
{{ html(asset('audio.mp3')) }}
{# Video #}
{{ html(asset('video.mp4')) }}

readtime

Détermine le temps de lecture d'un texte, en minutes.

{{ readtime(value) }}

Exemple:

{{ readtime(page.content) }} min

hash

Calcule le hachage d'un objet, d'un tableau ou d'une chaîne avec un algorithme donné.

{{ hash(value, algorithm) }}

algorithm peut être n'importe quel algorithme pris en charge par la fonction hash() de PHP (par exemple : md5, sha256, etc.). La valeur par défaut est xxh128.

Exemple:

{{ hash('my string', 'sha256') }}

cache_key

Calcule une clé de cache pour fragments cache en fonction d'un nom et d'une valeur facultative.

{% cache cache_key(name, value) %}
  {# cacheable content #}
{% endcache %}

La fonction ajoute un hachage de la valeur (peut être une chaîne, un tableau ou un objet) au nom (ainsi que la langue actuelle et l'ID de build pour être sûr que la clé de cache générée est unique), donc si la valeur est modifiée, la clé de cache est également modifiée et le cache est automatiquement vidé.

getenv

Obtient la valeur d'une variable d'environnement à partir de sa clé.

{{ getenv(var) }}

Exemple:

{{ getenv('VAR') }}

dump

La fonction dump affiche les informations sur une variable de modèle. Ceci est surtout utile pour déboguer un modèle qui ne se comporte pas comme prévu en introspectant ses variables :

{{ dump(user) }}

d

La fonction d() est la version HTML de dump() et utilise le Symfony VarDumper Component en arrière-plan.

{{ d(variable, {theme: light}) }}

• Si variable n'est pas fourni, la fonction renvoie le contexte Twig actuel
• Les thèmes disponibles sont « clair » (par défaut) et « sombre »

L'application transmet des variables aux templates pour manipulation dans le modèle. Les variables peuvent également avoir des attributs ou des éléments auxquels vous pouvez accéder. Utilisez un point (.) pour accéder aux attributs d'une variable : {{ foo.bar }}

Vous pouvez utiliser des variables de différentes portées : site, page, cecil.

site

La variable site contient des variables intégrées et celles définies dans la configuration.

Exemple:

title: "My amazing website!"

Peut être affiché dans un modèle avec :

{{ site.title }}

site.menus

Bouclez sur site.menus.<menu> pour obtenir chaque entrée de la collection <menu> (par exemple : main).

Exemple:

<nav>
  <ol>
  {% for entry in site.menus.main|sort_by_weight %}
    <li><a href="{{ url(entry.url) }}" data-weight="{{ entry.weight }}">{{ entry.name }}</a></li>
  {% endfor %}
  </ol>
</nav>

site.language

Informations sur la langue actuelle.

site.static

La collection de fichiers statiques est accessible via site.static si le static load est activé.

Chaque fichier expose les propriétés suivantes :

• path : chemin relatif (ex. : /images/img-1.jpg)
• date : date de création (timestamp)
• updated : date de modification (timestamp)
• name : nom (ex. : img-1.jpg)
• basename : nom sans extension (ex. : img-1)
• ext : poste (ex. : jpg)
• type : type de média (ex. : image)
• subtype : sous-type de média (ex. : image/jpeg)
• exif : données EXIF ​​​​de l'image (array)
• audio : Mp3Info objet
• video : tableau d'informations vidéo de base (durée en secondes, largeur et hauteur)

site.data

Une collection de données est accessible via site.data.<filename> (sans extension de fichier).

Exemples :

• data/authors.yml : site.data.authors
• data/authors.fr.yml : site.data.authors (si site.language = "fr")
• data/galleries/gallery-1.json : site.data.galleries['gallery-1']

page

La variable page contient les variables intégrées d'une page et celles définies dans le avant-plan.

Sections imbriquées

Dans un contexte de sections imbriquées, les propriétés page.parent, page.ancestors, page.sections et page.toplevel facilitent la construction de la navigation.

Fil d'Ariane (de la page d'accueil à la page courante) :

<nav aria-label="breadcrumb">
  <ul>
    <li><a href="{{ url(site.home) }}">{{ site.title }}</a></li>
    {% for section in page.ancestors|reverse %}
    <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
    {% endfor %}
    {% if page.id != site.home %}
    <li><a href="{{ url(page) }}" aria-current="page">{{ page.title }}</a></li>
    {% endif %}
  </ul>
</nav>

Menu des sous-sections (sections descendantes immédiates de la section courante) :

{% if page.sections|length %}
<ul>
  {% for section in page.sections|sort_by_title %}
  <li><a href="{{ url(section) }}">{{ section.title }}</a></li>
  {% endfor %}
</ul>
{% endif %}

Navigation principale limitée aux sections de premier niveau (depuis n'importe quelle page) :

<nav>
  {% for section in site.page(site.home).sections|sort_by_title %}
  <a href="{{ url(section) }}">{{ section.title }}</a>
  {% endfor %}
</nav>

Lien vers la section parente :

{% if page.parent %}
<a href="{{ url(page.parent) }}">← {{ page.parent.title }}</a>
{% endif %}

page.<prev/next>

Navigation entre les pages d'une même Section, triées selon le sortby de la section (ordre chronologique pour les dates).

Avec des sous-sections, la navigation suit l'arbre des sections : les pages d'une Section de premier niveau et de toutes ses sous-sections sont enchaînées, chaque sous-section (sa page d'index) étant placée parmi les pages de sa Section parente et suivie de ses propres pages.

Exemple:

<a href="{{ url(page.prev) }}">{{ page.prev.title }}</a>

page.paginator

Paginator vous aide à créer une navigation pour les pages de la liste : page d'accueil, sections et taxonomies.

Exemple:

{% if page.paginator %}
<div>
  {% if page.paginator.links.prev is defined %}
  <a href="{{ url(page.paginator.links.prev) }}">Previous</a>
  {% endif %}
  {% if page.paginator.links.next is defined %}
  <a href="{{ url(page.paginator.links.next) }}">Next</a>
  {% endif %}
</div>
{% endif %}

Exemple:

{% if page.paginator %}
<div>
  {% for paginator_index in 1..page.paginator.count %}
    {% if paginator_index != page.paginator.current %}
      {% if paginator_index == 1 %}
  <a href="{{ url(page.paginator.links.first) }}">{{ paginator_index }}</a>
      {% else %}
  <a href="{{ url(page.paginator.links.path ~ '/' ~ paginator_index) }}">{{ paginator_index }}</a>
      {% endif %}
    {% else %}
  {{ paginator_index }}
    {% endif %}
  {% endfor %}
</div>
{% endif %}

Taxonomie

Variables disponibles dans les templates vocabulary et term.

Vocabulaire

Page /<plural>/ (ex. : /categories/).

Chaque terme de page.terms fournit term.id (identifiant du terme, ex. : categories/php), term.name (nom du terme, ex. : PHP) et le nombre de ses pages avec term|length.

Terme

Page /<plural>/<term>/ (ex. : /categories/php/).

Exemple de taxonomie

Configuration :

taxonomies:
  categories: category

Front matter d’une page :

---
categories: ["Data Sovereignty"]
---

Liste des termes (/categories/), dans layouts/taxonomy/categories.html.twig :

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  <ul>
  {% for term in page.terms %}
    <li><a href="{{ url(term.id) }}">{{ term.name }}</a> ({{ term|length }})</li>
  {% endfor %}
  </ul>
{% endblock %}

Liste des pages d’un terme (/categories/data-sovereignty/), dans layouts/taxonomy/category.html.twig :

{% extends 'page.html.twig' %}

{% block content %}
  <h1>{{ page.title }}</h1>
  {% for p in page.paginator.pages ?? page.pages %}
    <article>
      <h2><a href="{{ url(p) }}">{{ p.title }}</a></h2>
    </article>
  {% endfor %}
  <a href="{{ url(page.plural) }}">Toutes les {{ page.plural }}</a>
{% endblock %}

Liens vers les termes de la page courante, dans un template de page :

{% for category in page.categories ?? [] %}
  <a href="{{ url('categories/' ~ category) }}">{{ category }}</a>
{% endfor %}

cecil

Tri des collections (de pages, menus ou taxonomies).

sort_by_title

Trie une collection par titre (avec tri naturel).

{{ collection|sort_by_title }}

Exemple:

{{ site.pages|sort_by_title }}

sort_by_date

Trie une collection par date (la plus récente en premier).

{{ collection|sort_by_date(variable='date', desc_title=false) }}

Exemple:

{# sort by date #}
{{ site.pages|sort_by_date }}
{# sort by updated variable instead of date #}
{{ site.pages|sort_by_date(variable='updated') }}
{# sort items with the same date by desc title #}
{{ site.pages|sort_by_date(desc_title=true) }}
{# reverse sort #}
{{ site.pages|sort_by_date|reverse }}

sort_by_weight

Trie une collection par poids (le plus léger en premier).

{{ collection|sort_by_weight }}

Exemple:

{{ site.menus.main|sort_by_weight }}

sort

Pour les cas plus complexes, vous devez utiliser le sort natif de Twig.

Exemple:

{% set files = site.static|sort((a, b) => a.date|date('U') < b.date|date('U')) %}

Les variables peuvent être modifiées par filtres. Les filtres sont séparés de la variable par un symbole de barre verticale (|). Plusieurs filtres peuvent être chaînés. La sortie d’un filtre est appliquée au suivant.

{{ page.title|truncate(25)|capitalize }}

filter_by

Filtre une collection de pages par nom/valeur de variable.

{{ collection|filter_by(variable, value) }}

Exemple:

{{ pages|filter_by('section', 'blog') }}

filter

Pour les cas plus complexes, vous devez utiliser le filter natif de Twig.

Exemple:

{% pages|filter(p => p.virtual == false and p.id not in ['page-1', 'page-2']) %}

markdown_to_html

Convertit une chaîne Markdown en HTML.

{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
{# Markdown here #}
{% endapply %}

Exemples :

{% set markdown = '**This is bold text**' %}
{{ markdown|markdown_to_html }}

{% apply markdown_to_html %}
**This is bold text**
{% endapply %}

toc

Extrait uniquement les en-têtes correspondant au selectors donné (h2, h3, etc.), ou à ceux définis dans la configuration pages.body.toc s'ils ne sont pas spécifiés. Le paramètre format définit le format de sortie : html ou json. Le paramètre url est utilisé pour créer des liens vers des titres.

{{ markdown|toc(format, selectors, url) }}

Exemples :

{{ page.body|toc }}
{{ page.body|toc('html') }}
{{ page.body|toc(selectors=['h2']) }}
{{ page.body|toc(url=url(page)) }}

json_decode

Convertit une chaîne JSON en tableau.

{{ json|json_decode }}

Exemple:

{% set json = '{"foo": "bar"}' %}
{% set array = json|json_decode %}
{{ array.foo }}

yaml_parse

Convertit une chaîne YAML en tableau.

{{ yaml|yaml_parse }}

Exemple:

{% set yaml = 'key: value' %}
{% set array = yaml|yaml_parse %}
{{ array.key }}

slugify

Convertit une chaîne en slug.

{{ string|slugify }}

u

Le filtre u enveloppe un texte dans un objet Unicode (une instance Symfony UnicodeString) qui expose des méthodes pour « manipuler » la chaîne.

Exemple:

{{ 'cecil_string with twig'|u.camel.title }}

CecilStringAvecTwig

singular

Le filtre singular transforme un nom donné au pluriel en sa version singulière.

{{ string|singular(locale)}}

Exemple:

{# English (en) rules are used by default #}
{{ 'partitions'|singular }}

partition

{{ 'partitions'|singular('fr') }}

partition

plural

Le filtre plural transforme un nom donné au singulier en sa version plurielle.

{{ string|plural(locale)}}

Exemple:

{# English (en) rules are used by default #}
{{ 'animal'|plural }}

animaux

{{ 'animal'|plural('fr') }}

animaux

excerpt

Tronque une chaîne et ajoute un suffixe.

{{ string|excerpt(length, suffix) }}

Exemples :

{{ variable|excerpt }}
{{ variable|excerpt(250, '...') }}

excerpt_html

Lit les caractères avant ou après la balise <!-- excerpt --> ou <!-- break -->. Voir Documentation de contenu pour plus de détails.

{{ string|excerpt_html({separator, capture}) }}

Exemples :

{{ variable|excerpt_html }}
{{ variable|excerpt_html({separator: 'excerpt|break', capture: 'before'}) }}
{{ variable|excerpt_html({capture: 'after'}) }}

highlight

Met en surbrillance une chaîne de code avec highlight.php.

{{ code|highlight(language) }}

Exemples :

{{ '<?php echo $highlighted->value; ?>'|highlight('php') }}

preg_split

Divise une chaîne en un tableau à l'aide d'une expression régulière.

{{ string|preg_split(pattern, limit) }}

Exemple:

{% set headers = page.content|preg_split('/<br[^>]*>/') %}

preg_match_all

Effectue une correspondance d'expression régulière et renvoie le groupe pour toutes les correspondances.

{{ string|preg_match_all(pattern, group) }}

Exemple:

{% set tags = page.content|preg_match_all('/<[^>]+>(.*)<\/[^>]+>/') %}

hex_to_rgb

Convertit une couleur hexadécimale en RVB.

{{ color|hex_to_rgb }}

Cecil fournit une logique de composants pour vous donner le pouvoir de créer des "unités" de templates réutilisables.

Syntaxe des composants

Les composants ne sont que des templates Twig stockés dans le sous-répertoire components/ et peuvent être utilisés n'importe où dans vos templates :

{# /components/button.twig #}
<button {{ attributes.merge({class: 'rounded px-4'}) }}>
    {{ slot }}
</button>

La variable slot correspond à tout contenu que vous ajouterez entre la balise d'ouverture et la balise de fermeture.

Pour accéder à un composant vous devez utiliser la balise dédiée x suivie de : et du nom de fichier de votre composant sans extension :

{# /index.twig #}
{% x:button with {class: 'text-white'} %}
    <strong>Click me</strong>
{% endx %}

Il rendra :

<button class="text-white rounded px-4">
    <strong>Click me</strong>
</button>

Cecil prend en charge traduction du texte et localisation de la date.

Traduction de texte

Utilise le trans tag ou filter pour traduire des textes dans des templates.

{% trans with variables into locale %}{% endtrans %}

{{ message|trans(variables = []) }}

Exemples

{% trans %}Hello World!{% endtrans %}

{{ message|trans }}

Inclure des variables :

{% trans with {'%name%': 'Arnaud'} %}Hello %name%!{% endtrans %}

{{ message|trans({'%name%': 'Arnaud'}) }}

Forcer les paramètres régionaux :

{% trans into 'fr_FR' %}Hello World!{% endtrans %}

Pluraliser :

{% trans with {'%count%': 42}%}{0}I don't have apples|{1}I have one apple|]1,Inf[I have %count% apples{% endtrans %}

Fichiers de traduction

Les fichiers de traduction doivent être nommés messages.<locale>.<extension> et stockés dans le répertoire translations. Les extensions prises en charge sont définies pour chaque format de traduction dans layouts.translations.formats.

Le code locale (ex. : fr_FR) d'une langue est défini dans les entrées languages de la configuration.

Exemple:

<mywebsite>
└─ translations
   ├─ messages.fr_FR.mo   <- Machine Object format
   └─ messages.fr_FR.yaml <- Yaml format

Localisation de la date

Utilise le filtre Twig format_date pour localiser une date dans les templates.

{{ page.date|format_date('long') }}
{# September 30, 2022 #}

Les valeurs prises en charge sont : short, medium, long et full.

Cecil utilise un système de cache pour accélérer le processus de génération, il peut être désactivé ou effacé.

Il existe trois types de cache dans le cas du rendu des templates : les templates eux-mêmes, assets et translations.

Vider le cache

Vous pouvez vider le cache avec les commandes suivantes :

php cecil.phar cache:clear               # clear all caches
php cecil.phar cache:clear:assets        # clear assets cache
php cecil.phar cache:clear:templates     # clear templates cache
php cecil.phar cache:clear:translations  # clear translations cache

Fragments de cache

Cecil fournit un moyen de mettre en cache des parties du rendu des templates pour éviter de restituer plusieurs fois le même contenu partiel.

Pour utiliser les fragments de cache, vous devez envelopper le contenu que vous souhaitez mettre en cache avec la balise cache.

{% cache 'unique-key' %}
  {# cacheable content #}
{% endcache %}

Pour vider uniquement le cache des fragments, vous pouvez utiliser la commande suivante :

php cecil.phar cache:clear:templates --fragments

Désactiver le cache

Vous pouvez désactiver le cache avec la configuration.

Fonctions et filtres

Vous pouvez ajouter des fonctions et des filtres personnalisés avec une extension Twig.

Thème

C'est simple de construire un thème, il suffit de créer un dossier <theme> avec la structure suivante (comme un site web mais sans pages) :

<mywebsite>
└─ themes
   └─ <theme>
      ├─ config.yml
      ├─ assets
      ├─ layouts
      ├─ static
      └─ translations