Les squelettes (depuis la version 1.1)

La syntaxe utilisée s'appelle Brindille. Elle ressemble à un mélange de Mustache, Smarty, Twig et PHP.

Son but est de permettre une grande flexibilité, sans avoir à utiliser un "vrai" langage de programmation, mais en s'en rapprochant suffisamment quand même.

Syntaxe de base

Affichage de variable

Une variable est affichée à l'aide de la syntaxe : {{$date}} affichera la valeur brute de la date par exemple : 2020-01-31 16:32:00.

La variable peut être modifiée à l'aide de filtres de modification, qui sont ajoutés avec le symbole de la barre verticale (pipe |) : {{$date|date_long}} affichera une date au format long : jeudi 7 mars 2021.

Ces filtres peuvent accepter des paramètres, séparés par deux points :. Exemple : {{$date|date:"%d/%m/%Y"}} affichera 31/01/2020.

Par défaut la variable sera recherchée dans le contexte actuel de la section, si elle n'est pas trouvée elle sera recherchée dans le contexte parent (section parente), etc. jusqu'à trouver la variable.

Il est possible de faire référence à une variable d'un contexte particulier avec la notation à points : {{$article.date}}.

Il existe deux variables de contexte spécifiques : $_POST et $_GET qui permettent d'accéder aux données envoyées dans un formulaire et dans les paramètres de la page.

Par défaut le filtre escape est appliqué à toutes les variables pour protéger les variables contre les injections de code HTML. Ce filtre est appliqué en dernier, après les autres filtres. Il est possible de contourner cet automatisme en rajoutant le filtre escape ou raw explicitement. raw désactive tout échappement, mais escape est utilisé pour changer l'ordre d'échappement. Exemple :

{{* $text = "Coucou
ça va ?" *}}
{{$text|nl2br|escape}}

Donnera bien Coucou<br />ça va ?. Sans indiquer le filtre escape le résultat serait Coucou&lt;br /&gt;ça va ?.

Conditions

Il est possible d'utiliser des conditions de type "si" (if), "sinon si" (elseif) et "sinon" (else). Celles-ci sont terminées par un block "fin si" (/if).

{{if $date|date:"%Y" > 2020}}
    La date est en 2020
{{elseif $article.is_draft}}
    La page est un brouillon
{{else}}
    Autre chose.
{{/if}}

Fonctions

Une fonction va répondre à certains paramètres et renvoyer un résultat ou réaliser une action. Un bloc de fonction commence par le signe deux points : :

{{:http code=404}}

Contrairement aux autres types de blocs, et comme pour les variables, il n'y a pas de bloc fermant (avec un slash /).

Sections

Une section est une partie de la page qui sera répétée une fois, plusieurs fois, ou zéro fois, selon ses paramètres et le résultat (c'est une "boucle"). Une section commence par un bloc avec un signe hash (#) et se termine par un bloc avec un slash (/).

Un exemple simple avec une section qui n'aura qu'une seule répétition :

{{#categories uri=$_GET.uri}}
    <h1>{{$title}}</h1>
{{/categories}}

Il est possible d'utiliser une condition {{else}} avant la fin du bloc pour avoir du contenu alternatif si la section ne se répète pas (dans ce cas si aucune catégorie ne correspond au critère).

Un exemple de sous-section

{{#categories uri=$_GET.uri}}
    <h1>{{$title}}</h1>

    {{#articles parent_id=$id order="created DESC" limit="10"}}
        <h2><a href="{{$url}}">{{$title}}</a></h2>
        <p>{{$text|truncate:600:"..."}}</p>
    {{else}}
        <p>Aucun article trouvé.</p>
    {{/articles}}

{{/categories}}

Voir la référence des sections pour voir quelles sont les sections possibles et quel est leur comportement.

Sections litérales

Pour qu'une partie du code ne soit pas interprété, pour éviter les conflits avec certaines syntaxes, il est possible d'utiliser un bloc literal :

{{literal}}
<script>
// Ceci ne sera pas interprété
function test (a) {{
}}
</script>
{{/literal}}

Commentaires

Les commentaires sont figurés dans des blocs qui commencent et se terminent par une étoile (*) :

{{* Ceci est un commentaire
Il sera supprimé du résultat final
Il peut contenir du code qui ne sera pas interprété :
{{if $test}}
OK
{{/if}}
*}}

Référence des fonctions disponibles

debug

Cette fonction permet d'afficher le contenu d'une ou plusieurs variables :

{{{debug test=$title}}}

Affichera :

array(1) {
  ["test"] => string(6) "coucou"
}

Si aucun paramètre n'est spécifié, alors toutes les variables définies sont renvoyées. Utile pour découvrir quelles sont les variables accessibles dans une section par exemple.

http

Permet de modifier les entêtes HTTP renvoyés par la page. Cette fonction doit être appelée au tout début du squelette, avant tout autre code ou ligne vide.

Un seul de ces paramètres peut être utilisé à la fois :

code Modifie le code HTTP renvoyé. Liste des codes HTTP
redirect Rediriger vers l'adresse URI indiquée en valeur. Seules les adresses internes sont acceptées, il n'est pas possible de rediriger vers une adresse extérieure.
type Modifie le type MIME renvoyé

Exemples :

{{:http code=404}}
{{:http redirect="/Nos-Activites/"}}
{{:http type="application/svg+xml"}}

Référence des sections

Dans toutes les sections il est possible d'utiliser les paramètres suivants :

where Condition de sélection des résultats
begin Début des résultats, si vide une valeur de 0 sera utilisée.
limit Limitation des résultats. Si vide, une valeur de 1000 sera utilisée.
order Ordre de tri des résultats. Si vide le tri sera fait par ordre d'ajout dans la base de données.
debug Si ce paramètre existe, la requête SQL exécutée sera affichée avant le début de la boucle.

Il est également possible de passer des arguments dans les paramètres à l'aides des arguments nommés qui commencent par deux points : : {{#articles order=":order DESC" :order="date"}}

sql

Effectue une requête SQL de type SELECT dans la base de données.

{{#sql select="*, julianday(date) AS day" tables="membres" where="id_categorie = :id_categorie" :id_categorie=$_GET.id_categorie order="numero DESC" begin=":page*100" limit=100 :page=$_GET.page}}
…
{{/sql}}

Paramètres possibles

tables Liste des tables à utiliser dans la requête. Ce paramètre est obligatoire.
select Liste des colonnes à sélectionner, si non spécifié, toutes les colonnes (*) seront sélectionnées
group Contenu de la clause GROUP BY

pages, articles, categories

  • pages renvoie une liste de pages, qu'elles soient des articles ou des catégories
  • categories ne renvoie que des catégories
  • articles ne renvoie que des articles

À part cela les trois types de section se comportent de manière identique

Paramètres possibles

search Renseigner ce paramètre avec un terme à rechercher dans le texte ou le titre. Dans ce cas par défaut le tri des résultats se fait sur la pertinence, sauf si le paramètre order est spécifié.

files, documents, images

  • files renvoie une liste de fichiers
  • documents renvoie une liste de fichiers qui ne sont pas des images
  • images renvoie une liste de fichiers qui sont des images

À part cela les trois types de section se comportent de manière identique

Note : seul les fichiers de la section site web sont accessibles, les fichiers de membres, de comptabilité, etc. ne sont pas disponibles.

Paramètres possibles

except_in_text passer à ce paramètre un texte, et seuls les fichiers qui ne sont pas liés dans le texte seront renvoyés : except_in_text=$text

Paramètres

Référence des filtres disponibles

escape

raw

args

nl2br

strip_tags

count

cat

date_format

Modifications dans la version 1.1

La version 1.1 passe de la syntaxe des squelettes SPIP à la nouvelle syntaxe "Brindille" (voir ci-dessus). Les anciens squelettes du répertoire squelettes ne seront plus utilisés, vous devrez re-créer vos squelettes à la main dans l'interface de Garradin. Malheureusement après 9 ans d'utilisation les squelettes SPIP n'étaient plus suffisants et ne pourront plus être utilisés. Cependant la logique reste très similaire, mais la syntaxe se rapproche de celle de Smarty et PHP pour faciliter l'utilisation par les personnes ayant déjà une expérience en programmation.

Le fichier www/squelettes/mes_filtres.php n'est plus utilisé. Un nouvel événement usertemplate.init est lancé à l'initialisation d'un squelette, au moment d'enregistrer les filtres et sections. Utilisez une extension (plugin) pour enregistrer filtres et sections personnalisés. Vous pouvez utiliser le paramètre template pour accéder à l'objet UserTemplate du squelette et y enregistrer vos filtres et sections à l'aide des méthodes ->registerModifier($name, $callback); et ->registerSection($name, $callback);. Voir le fichier include/lib/Garradin/UserTemplate.php pour des exemples.

Changements divers :

  • Le squelette par défaut pour la page d'accueil n'est plus sommaire.html mais index.html
  • Tout squelette dont le nom de fichier existe sera appelé directement
  • Les rubriques ont été renommées catégories
  • Il est désormais possible de faire une requête SQL arbitraire sur n'importe quelle table via le type de section sql

Les squelettes dans Garradin (jusqu'à la version 1.0)

Cette syntaxe, proche de SPIP, n'est plus utilisée, mais la documentation peut toujours être [consultée].