// BLOG

Kirby CMS - Les snippets

Il est courrant dans un site web que certaines parties du code se répètent à plusieurs endroits. Pour éviter de dupliquer des lignes de codes dans vos fichiers, Kirby met à votre disposition un type de fichiers bien pratique : les snippets.

Rédigé le 16.03.2022

Par Gilles Vauvarin

Snippets Kirby CMS PHP

Qu'est ce qu'un snippet ?

Un snippet est un morceau de code (HTML, CSS, JS, PHP) écrit dans un fichier PHP et que vous pouvez réutiliser n'importe où dans un template. Les fichiers snippets doivent être stockés dans le dossier /site/snippets/ et vous pouvez leur donner le nom que vous souhaitez. Pour des raisons d'organisation, vous pouvez également créer des sous-dossiers dans le dossier /site/snippets/ pour ranger vos snippets par thématique.

Exemples :

/site/snippets/header.php

/site/snippets/footer.php

/site/snippets/sidebar.php

/site/snippets/projects/author.php

/site/snippets/projects/clients.php

Quand utiliser les snippets ?

A partir du moment où une séquence de lignes de code se répète au moins deux fois dans votre projet, vous avez tout intérêt à isoler cette séquence de code dans un snippet et appeler ce snippet aux endroits voulus. Vous gagnerez du temps si un jour vous devez modifier une partie de cette séquence de code car le changement ne se fera qu'à un seul endroit.

Comment utiliser les snippets ?

Kirby met à votre disposition une fonction snippet() pour importer votre séquence de code dans vos templates.

Cette fonction accepte trois paramètres : $name, $data et $return . Seul le premier paramètre $name est obligatoire.

Paramètre	Usage
$name	Il s'agit du nom du snippet à importer. Ce nom est celui donné au fichier PHP stocké dans /site/snippets/
$data	Votre snippet peut contenir des variables PHP que vous pouvez alimenter avec une valeur au moment de l'appel du snippet.
$return	Ce paramètre boolean permet d'indiquer si vous souhaiter afficher le rendu du snippet ou le retourner pour le stocker dans une variable par exemple.

Voici quelques exemples :

Si je décide d'exporter le code qui affiche mon footer dans un snippet, je pourrais avoir le fichier suivant : /site/snippets/footer.php

// /site/snippets/footer.php

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

</body>
</html>

Maintenant, si je souhaite appeler mon snippet "footer" dans mes templates, j'écrirais le code suivant :

// /site/templates/about.php

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

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

  <main>
    <?= $page->text() ?>
  </main>

  // Include the footer snippet
  <?php snippet('footer') ?>

Si mon snippet "footer" était stocké dans un sous-répertoire, par exemple /site/snippet/footer/footer-a.php je l'aurais appelé de la façon suivante dans mon template :

// /site/templates/about.php

...

<?php snippet('footer/footer-a') ?>

Supposons maintenant que nous ayons une variable $cms dans le snippet "footer"

// /site/snippets/footer.php

<footer>
    <div>Made with love with <?= $cms ?></div>
</footer>

</body>
</html>

Nous pourrions affecter une valeur à cette variable lors de l'appel du snippet dans le template de la façon suivante :

// /site/templates/about.php

...
  
<?php snippet( 'footer' , ['cms' => 'Craft CMS'] ); ?>

Maintenant, supposons que vous souhaitiez récupérer le rendu du snippet "footer" dans une variable $footer pour la réutiliser plus tard dans votre template. On procédera ainsi :

// /site/templates/about.php

...
  
<?php 

$footer = snippet( 'footer' , ['cms' => 'Craft CMS'] , true );

...

echo $footer;

?>

Lorsque l'on affecte le rendu d'un snippet dans une variable, les snippets peuvent être utilisés dans une variété de situations et pas seulement dans un template.

Appeler des snippets alternatives

Dans certains cas, il peut être intéressant d'avoir la possibilité d'indiquer différents snippets comme alternative au cas où le premier snippet appelé ne serait pas disponible. Dans ce cas, la fonction snippet() s'utiliserait ainsi :