Artifact ID: | db9525db6a04a84817db5a91e2ff869069ccc28c4a1cbe4d2e4739ba500c8535 |
---|---|
Page Name: | Documentation/Brindille |
Date: | 2021-11-25 22:59:24 |
Original User: | bohwaz |
Mimetype: | text/x-markdown |
Parent: | 0a63c030affec4febb360efca1ea672e031e3fdd1f95645f09813656e992e9a2 (diff) |
Next | 8f747be54565e091b4da907387130a6ca3f31718281209b1db0c988876a1f116 |
Brindille, la syntaxe des squelettes et des modèles
La syntaxe utilisée s'appelle Brindille. Si vous avez déjà fait de la programmation, 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<br />ça va ?
.
Ordre de recherche des variables
Par défaut les variables sont recherchées dans l'ordre inverse, c'est à dire que sont d'abord recherchées les variables avec le nom demandé dans la section courante. Si la variable n'existe pas dans la section courante, alors elle est recherchée dans la section parente, et ainsi de suite jusqu'à ce que la variable soit trouvée, où qu'il n'y ait plus de section parente.
Prenons cet exemple :
{{#articles uri="Actualite"}}
<h1>{{$title}}</h1>
{{#images parent=$path limit=1}}
<img src="{{$thumb_url}}" alt="{{$title}}" />
{{/images}}
{{/articles}}
Dans la section articles
, $title
est une variable de l'article, donc la variable est celle de l'article.
Dans la section images
, les images n'ayant pas de titre, la variable sera celle de l'article de la section parente, alors que $thumb_url
sera lié à l'image.
Conflit de noms de variables
Imaginons que nous voulions mettre un lien vers l'article sur l'image de l'exemple précédent :
{{#articles uri="Actualite"}}
<h1>{{$title}}</h1>
{{#images parent=$path limit=1}}
<a href="{{$url}}"><img src="{{$thumb_url}}" alt="{{$title}}" /></a>
{{/images}}
{{/articles}}
Problème, ici $url
fera référence à l'URL de l'image elle-même, et non pas l'URL de l'article.
La solution est d'ajouter un point au début du nom de variable : {{$.url}}
.
Un point au début d'un nom de variable signifie que la variable est recherchée à partir de la section précédente. Il est possible d'utiliser plusieurs points, chaque point correspond à un niveau à remonter. Ainsi $.url
cherchera la variable dans la section parente (et ses sections parentes si elle n'existe pas, etc.). De même, $..url
cherchera dans la section parente de la section parente.
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=$path order="published 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
assign
Permet d'assigner une valeur dans une variable :
{{:assign blabla="Coucou"}}
{{$blabla}}
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
foreach
Permet d'itérer sur un tableau par exemple :
{{#foreach from=$variable}}
{{$key}} = {{$value}}
{{/foreach}}
Référence des sections SQL
Dans toutes les sections héritées de sql
suivantes 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 where="title = :montitre" :montitre="Actualité"}}
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 (héritent de sql)
pages
renvoie une liste de pages, qu'elles soient des articles ou des catégoriescategories
ne renvoie que des catégoriesarticles
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é. Dans ce cas une variable $snippet sera disponible à l'intérieur de la boucle, contenant les termes trouvés. |
future |
Renseigner ce paramètre à false pour que les articles dont la date est dans le futur n'apparaissent pas, true pour ne renvoyer QUE les articles dans le futur, et null (ou ne pas utiliser ce paramètre) pour que tous les articles, passés et futur, apparaissent. |
parent |
Indiquer ici le chemin d'article ou de catégorie parente. Utile pour renvoyer par exemple la liste des articles d'une catégorie. |
files, documents, images (héritent de sql)
files
renvoie une liste de fichiersdocuments
renvoie une liste de fichiers qui ne sont pas des imagesimages
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
parent (obligatoire) |
Chemin (adresse unique) de l'article ou catégorie parente dont ont veut lister les fichiers |
except_in_text |
passer true à ce paramètre , et seuls les fichiers qui ne sont pas liés dans le texte de la page seront renvoyés |
breadcrumbs
Permet de récupérer la liste des pages parentes d'une page afin de constituer un fil d'ariane) permettant de remonter dans l'arborescence du site
Un seul paramètre est possible :
path (obligatoire) |
Chemin (adresse unique) de la page parente |
---|
Chaque itération renverra trois variables :
$title |
Titre de la page ou catégorie |
$url |
Adresse HTTP de la page ou catégorie |
$path |
Chemin (adresse unique) de la page ou catégorie |
Exemple
{{#breadcrumbs path=$page.path}}
→ <a href="{{ $url }}">{{ $title }}</a><br />
{{/breadcrumbs}}
Référence des filtres disponibles
Filtres PHP
Ces filtres viennent directement de PHP et utilisent donc les mêmes paramètres :
- strtolower
- strtoupper
- ucfirst
- ucwords
- htmlentities
- htmlspecialchars
- trim, ltrim, rtrim
- lcfirst
- md5
- sha1
- metaphone
- soundex
- str_split
- str_word_count
- strrev
- strlen
- strip_tags
- nl2br
- wordwrap
- strlen
truncate
Arguments :
- nombre : longueur en nombre de caractères (défaut = 80)
- texte : texte à placer à la fin (si tronqué) (défaut = …)
- booléen : coupure stricte, si
true
alors un mot pourra être coupé en deux, sinon le texte sera coupé au dernier mot complet
Tronque un texte à une longueur définie.
excerpt
Produit un extrait d'un texte.
Supprime les tags HTML, tronque au nombre de caractères indiqué en second argument (si rien n'est indiqué, alors 600 est utilisé), et englobe dans un paragraphe <p>...</p>
.
Équivalent de :
<p>{{$text|strip_tags|truncate:600|nl2br}}</p>
protect_contact
Crée un lien protégé pour une adresse email, pour éviter que l'adresse ne soit recueillie par les robots spammeurs (empêche également le copier-coller et le lien ne fonctionnera pas avec javascript désactivé).
escape
Échappe le contenu pour un usage dans un document HTML. Ce filtre est appliqué par défaut à tout ce qui est affiché (variables, etc.) sauf à utiliser le filtre raw
(voir plus bas).
xml_escape
Échappe le contenu pour un usage dans un document XML.
raw
Passer ce filtre désactive la protection automatique contre le HTML (échappement) dans le texte. À utiliser en connaissance de cause avec les contenus qui contiennent du HTML et sont déjà filtrés !
{{"<b>Test"}} = <b>Test
{{"<b>Test"|raw}} = <b>Test
args
Remplace des arguments dans le texte selon le schéma utilisé par sprintf.
{{"Il y a %d résultats dans la recherche sur le terme '%s'."|args:$results_count:$query}}
= Il y a 5 résultat dans la recherche sur le terme 'test'.
count
Compte le nombre d'entrées dans un tableau.
{{$products|count}}
= 5
cat
Concaténer un texte avec un autre.
{{"Tangerine"|cat:" Dream"}}
= Tangerine Dream
replace
Remplace des parties du texte par une autre partie.
{{"Tata yoyo"|replace:"yoyo":"yaya"}}
= Tata yaya
regexp_replace
Remplace des valeurs en utilisant une expression rationnelles (regexp) (documentation PHP).
{{"Tartagueule"|regexp_replace:"/ta/i":"tou"}}
= tourtougueule
size_in_bytes
Renvoie une taille en octets, Ko, Mo, ou Go à partir d'une taille en octets.
{{100|size_in_bytes}} = 100 o
{{1500|size_in_bytes}} = 1,50 Ko
{{1048576|size_in_bytes}} = 1 Mo
typo
Pour le français.
Ajoute des espaces insécables (
) devant ou derrière les ponctuations françaises (« » ? ! :
).
money
Formatte une valeur de monnaie (exprimée avec les cents inclus : 1502
= 15,02) pour l'affichage :
{{$amount|money}}
15,02
money_currency
Formatte une valeur de monnaie en ajoutant la devise :
{{$amount|money_currency}}
15,02 €
Filtres de date
date
: formatte une date selon un format spécifié (identique au format utilisé par PHP). Si aucun format n'est utilisé, le défaut serad/m/Y à H:i
. (en français)strftime
: formatte une date selon un format spécifié, identique au format utilisé par la fonction strftime de PHP. Un format doit obligatoirement être spécifié. En passant un code de langue en second paramètre, cette langue sera utilisée. Sont supportés le français (fr
) et l'anglais (en
). Le défaut est le français si aucune valeur n'est passée en second paramètre .relative_date
: renvoie une date relative à la date du jour :aujourd'hui
,hier
,demain
, ou sinonmardi 2 janvier
(si la date est de l'année en cours) ou2 janvier 2021
(si la date est d'une autre année). En spécifianttrue
en second paramètre, l'heure sera ajoutée au format14h34
.date_short
: date au format court :d/m/Y
, en spécifianttrue
en second paramètre l'heure sera ajoutée :à H\hi
.date_long
: date au format long :lundi 2 janvier 2021
. En spécifianttrue
en second paramètre l'heure sera ajoutée :à 20h42
.date_hour
: renvoie l'heure uniquement à partir d'une date :20h00
. En passanttrue
en second paramètre, les minutes seront omises si elles sont égales à zéro :20h
.atom_date
: formatte une date au format ATOM :Y-m-d\TH:i:sP