// BLOG

screenshot

Kirby CMS - Les templates

Les templates correspondent aux vues frontend de votre site Kirby. Ils sont chargés d'afficher et de présenter votre contenu à l'écran. Nous allons voir dans cet article comment fonctionne les templates et comment ils sont liés à vos fichiers textes.

Rédigé le 12.03.2022
Par Gilles Vauvarin

Kirby CMS Templates PHP

Qu'est ce qu'un template ?

C'est un fichier PHP que l'on place toujours dans le dossier /site/templates/ et qui sera chargé de structurer et d'afficher vos contenus stockés dans les fichiers textes du dossier /content. Dans un fichier templates, vous pouvez écrire du HTML, du CSS, du JavaScript et du PHP. Vous aurez aussi accès à toutes les méthodes et objets mis à disposition par Kirby.

Lier un template à un contenu

Kirby fait le lien entre un fichier texte du dossier /content/ et un fichier PHP template du dossier /site/templates/ grâce au nommage de ces fichiers. En effet, tous les fichiers textes qui porteront le nom post.txt par exemple, seront pris en charge par un template nomé post.php

Voici d'autres exemples pour illustrer ce fonctionnement :

Fichier texte stocké dans le dossier /content/ Fichier PHP template stocké dans le dossier /site/templates/
/content/home/home.txt /site/templates/home.php
/content/about/about.txt /site/templates/about.php
/content/posts/post-a/post.txt /site/templates/post.php
/content/posts/post-b/post.txt /site/templates/post.php
Vous noterez que les contenus similaires (ici les posts) peuvent partager un même template.

Pour effectuer cette liaison entre contenu et template, si vous travaillez à la main avec les fichiers, sans passer par le panel, c'est à vous de bien faire correspondre les noms des fichiers textes avec celui des templates que vous voulez appliquer. Si vous passez par le panel, à la création d'une page, Kirby vous laissera choisir le template que vous voulez appliquer via un menu déroulant placé dans la modal de création d'une page.

Le template default.php

C'est une bonne pratique de créer un template nommé default.php dans le dossier /site/templates que Kirby appliquera par défaut à tout contenu non lié à un template. Par exemple, si vous travaillez à la main avec vos fichiers (pas d'usage du panel) et que vous faites une erreur dans l'ortographe du nom du fichier texte, Kirby ne trouvera pas le template correspondand et appliquera alors le template /site/templates/default.php en dernier ressort. Cela permet d'afficher un contenu à votre utilisateur plutôt qu'un message d'erreur le temps que vous vous rendiez compte du problème.

Accéder à votre contenu depuis le template

L'API de Kirby mets à notre disposition dans chaque template les variables $site $pages et $page

Ces variables nous permettent d'accéder à tous les contenus du site et des pages, c'est à dire à toutes les valeurs contenus dans les fichiers textes du dossier /content

La variable $site

Cet objet permet d'accéder aux informations générales sur le site (URL racine ...) et toutes les valeurs qui seront contenus dans le fichier /content/site.txt Vous aurez également accès à plusieurs méthodes de l'objet $site que vous pouvez trouver dans la documentation de Kirby.

Vous n'avez pas besoin de créer un template spécifique /site/templates/site.php pour accéder aux valeurs des données contenus dans ce fichier texte. En effet, le contenu du fichier site.txt est accessible par tous les templates.

Le fichier texte /content/site.txt est le parfait candidat pour stocker toutes informations relatives à votre site web et que vous souhaitez accessible sur l'ensemble des pages du site. Par exemple les informations SEO, les informations liées à vos réseaux sociaux ...

Prenons l'exemple de ce fichier /content/site.txt

// /content/site.txt

Title: My Website

----

Description: This is my first Kirby website.

Ce contenu pourrait être récupéré dans votre template /site/templates/home.php de la façon suivante :

// /site/templates/home.php

<html>
<head>
  <meta charset="UTF-8">
  <meta name="description" content="<?= $site->description()->html() ?>">
  <title>
    <?= $site->title()->html() ?>
  </title>
</head>
<body>

  <header>
    <h1 class="logo">
      <a href="<?= $site->url() ?>">
        <?= $site->title()->html() ?>
      </a>
    </h1>
  </header>

  Hello world!

  <footer>
    <p>Made with love with Kirby</p>
  </footer>

</body>
</html>
Vous noterez que chaque clé du fichier texte /content/site.txt peut être appelée comme une méthode à l'aide d'une flèche, synthaxe utilisée en PHP pour appeler des méthodes de classe. Le code PHP $site->title() dans le template, récupère la valeur affectée à la clé "Title" du fichier texte /content/site.txt soit ici la valeur "My Website".

La variable $pages

L'objet $pages fait référence à une collection de pages. L'objet $pages n'existe pas en tant que tel, c'est à vous de le déclarer et l'alimenter. Les pages de cette collection peuvent avoir des parents identiques ou différents. Par exemple une collection pourrait être l'ensemble des articles de votre blog (parent identique) ou une séléction choisie de pages de votre site (parents différents).

Exemple : 

// /site/templates/home.php

...

<? 
$posts = $site->find('blog')->children();
$specific_pages = $site->find('blog', 'projects', 'about');
?>

Ici les variables $posts et $specific_pages sont des objets $pages, et on peut accéder depuis ces deux objets à toutes les méthodes de l'objet $pages indiquées dans la documentation.

Pour accéder aux valeurs de chacune des pages d'une collection et les afficher à l'écran, vous devrez utiliser une boucle en PHP dans votre template.

La variable $page

L'objet $page se réfère toujours à la page en cours, c'est à dire à la page actuellement visitée par l'utilisateur. Si l'utilisateur charge la page "about" dans son navigateur, le template /site/templates/about.php sera appelé et l'objet $page dans ce template fera référence à la page "about" c'est à dire le fichier /content/about/about.txt

Vous trouverez les méthodes associées à l'objet $page dans la documentation de Kirby.

Voici par exemple le contenu du fichier about.txt

Title: About

----

Content: Lorem ipsum ...

Dans le template /site/templates/about.php nous aurons accès aux valeurs de la page de la façon suivante :

// /site/template/about.php

<html>
<head>
  <meta charset="UTF-8">
  <meta name="description" content="<?= $site->description()->html() ?>">
  <title>
    <?= $site->title()->html() ?>
  </title>
</head>
<body>

  <header>
    <h1>
        <?= $page->title()->html() ?>
      </a>
    </h1>
  </header>

 <container>
  <div>
    <?= $page->content()->html() ?>
  </div>
 </container>

  <footer>
    <p>Made with love with Kirby</p>
  </footer>

</body>
</html>
La méthode html() utilisée ici est une méthode d'échapement qui encode les caractères spéciaux par sécurité.
Les noms des clés dans le fichier texte sont convertis en minuscules dans le template et toute ponctuation est remplacée par des caractères de soulignement car PHP ne supporte pas les caractères spéciaux dans les noms de méthodes.

La vidéo YouTube