// BLOG
Kirby CMS - Les layouts
Si vous êtes familié des frameworks JS comme React, Vue ou Svelte, vous connaissez la notion de slot. Les layouts dans Kirby sont des structures de contenu dans lesquelles on place des "trous" ou "slot" qui peuvent être remplis par d'autres contenus.
Les layouts/slots dont nous allons parler dans cet article n'est pas une fonctionnalité intégrée dans le core de Kirby mais disponible sous la forme d'un plugin dévelopé par les membres de l'équipe Kirby. Si vous installez ce plugin dans votre projet Kirby, vous pourrez créer des layouts et des slots qui seront utilisables depuis vos templates.
Qu'est ce qu'un layout ?
Un layout est un fichier PHP qui définie une structure HTML, CSS et dans laquelle on a positionné un ou plusieurs slots. Les slots sont comme des "fentes" présentent dans la page et dans lesquelles on pourra insérer des contenus provenant de templates.
Vous pouvez créer autant de layouts que vous le souhaitez et un layout peut contenir un ou plusieurs slots.
Comment créer un layout ?
Un layout est un fichier PHP qui sera stocké dans un dossier /site/layouts/ Vous êtes libre du nom que vous lui donnerez. Vous devez prévoir d'y insérer au moins un slot pour qu'il soit utilisable, le rôle d'un layout étant de proposer une structure dans laquelle on peut insérer un contenu. Pour appeler ce layout depuis votre template, vous devrez utiliser la méthode layout('nom-du-layout-a-utiliser')
Vous pouvez créer un layout qui sera appelé par défaut si lors de l'appel du layout dans vos templates, vous n'indiquez pas de nomlayout(). Ce layout par défaut devra alors être nomé/site/layouts/default.php
Créons par exemple un layout "two-columns" : /site/layouts/two-columns.php
<?php
// /site/layouts/two-columns.php
?>
<html>
<head>
<title><?= $page->title() ?></title>
</head>
<body>
<div class="sidebar">
<?php slot() ?> <!-- Le slot est ici ! -->
<?php endslot() ?>
</div>
<div class="main">
<h2><?= $page->title() ?></h2>
<p><?= $page->content() ?></p>
</div>
</body>
</html>Si vous déclarez qu'un seul slot dans votre layout, la balise fermante endslot() est optionnelle.
Le layout two-columns pourra être appelé depuis n'importe quel template grâce à la méthode Kirby layout() à laquelle vous passerez en paramètre le nom du layout à utiliser de la manière suivante :
<?php
// /site/templates/product.php
layout('two-columns');
?>
<nav>
<ul>
<li>Home</li>
<li>Blog</li>
<li>About</li>
</ul>
</nav>Dans ce cas, le code contenu dans le template product.php (ici un simple menu) sera injecté à l'emplacement du slot du layout appelé two-columns.php ce qui au final donnera le rendu suivant :
<html>
<head>
<title>Mon titre</title>
</head>
<body>
<div class="sidebar">
<nav>
<ul>
<li>Home</li>
<li>Blog</li>
<li>About</li>
</ul>
</nav>
</div>
<div class="main">
<h2>Mon titre</h2>
<p>Lorem ipsum</p>
</div>
</body>
</html>Déclarer plusieurs slots dans un layout
Vous pouvez placer plusieurs slots dans un layout aux endroits que vous voulez. Dans ce cas, vous devez penser à cloturer vos slots avec une méthode endslot() de fermeture et vous devez nommer les slots supplémentaires.
Le slot qui n'est pas nomé sera le slot par défaut. Il sera utilisé si aucun nom de slot n'est indiqué dans le template.
Il est également possible de prévoir un contenu par défaut à afficher dans un slot si celui-ci n'est pas utilisé dans le template.
Voyons un exemple concret pour illustrer ces différents points :
<?php
// /site/layouts/two-columns.php
?>
<html>
<head>
<?php slot('head') ?>
<title>Product</title> <!-- Premier slot nomé avec contenu par défaut si pas utilisé -->
<?php endslot() ?>
</head>
<body>
<div class="sidebar">
<?php slot('sidebar') ?>
<!-- Second slot nomé sans contenu par défaut -->
<?php endslot() ?>
</div>
<div class="main">
<?php slot() ?>
<!-- Troisième slot non nomé - slot par défaut -->
<?php endslot() ?>
</div>
</body>
</html>Au niveau du template, nous pourrons utiliser les slots de la manière suivante :
<?php
// /site/templates/product.php
layout('two-columns');
?>
<?php slot('sidebar') ?>
<nav>
<!-- ... du code html/CSS/JS/PHP pour un menu ici -->
</nav>
<?php endslot() ?>
<?php slot() ?>
<!-- ... du code html/CSS/JS/PHP ici -->
<?php endslot() ?>Utiliser des snippets dans un layout
Utiliser des layouts ne vous interdit pas d'utiliser des snippets, vous pouvez très bien appeler un snippet dans un slot par exemple :
<?php
// /site/layouts/two-columns.php
?>
<html>
<head>
<?php slot('head') ?>
snippet('head') <!-- Slot avec contenu par défaut fournit par un snippet -->
<?php endslot() ?>
</head>
<body>
<div class="sidebar">
<?php slot('sidebar') ?>
<?php endslot() ?>
</div>
<div class="main">
<?php slot() ?>
<?php endslot() ?>
</div>
</body>
</html>Passer des données globales dans la méthode layout()
Il est possible de passer en second paramètre de la méthode layout() un tableau avec des données qui seront disponibles dans les slots et les snippets de notre layout :
<?php
// /site/layouts/two-columns.php
?>
<html>
<head>
<?php slot('head') ?>
<title><?= $title ?></title>
<!-- $title peut être alimentée par une valeur au moment de l'appel du layout -->
<?php endslot() ?>
</head>
<body>
<div class="sidebar">
<?php slot('sidebar') ?>
<?php endslot() ?>
</div>
<div class="main">
<?php slot() ?>
<?php endslot() ?>
</div>
</body>
</html>Dans le template, nous pourrons alimenter la variable $title en passant une valeur en second paramètre de la méthode layout() :
<?php
// /site/template/product.php
layout('two-columns', ['title' => 'Mon titre ')
?>
<?php ?>
<?php slot('sidebar') ?>
<nav>
<!-- ... du code html/CSS/JS/PHP pour un menu ici -->
</nav>
<?php endslot() ?>
<?php slot() ?>
<!-- ... du code html/CSS/JS/PHP ici -->
<?php endslot() ?>Voilà, c'est out pour les layouts. Ce qu'il faut retenir c'est que comme les snippets, les layouts vous permettent de factoriser votre code et donc de favoriser la maintenance et la clarté du code.