Skip to main content

CHAPITRE 19 — La grammaire des slots en détail

Référence exhaustive de tous les types de slot et de leurs attributs. Gardez ce chapitre à portée de main lors de l'annotation d'un template.

Format général

{{slot:<name>|type=<type>|default=<value>|label=<text>|group=<section>|help=<text>|maxlength=<int>|options=<csv>}}

Tous les attributs, à l'exception de name et type, sont facultatifs. L'ordre est libre. Le séparateur est le caractère pipe.

Règles syntaxiques

Règle

Détail

Identifiant

[a-z0-9_]+

, 64 caractères maximum. Pas de tirets, pas de majuscules.

Unicité

Unique par page. Deux slots avec le même nom sur la même page produisent un avertissement au scan.

Pas d'espaces

Aucun espace de part et d'autre du signe

=

. Aucun espace dans les noms d'attributs.

Échappement

Le pipe à l'intérieur d'une valeur n'est pas pris en charge. Évitez-le dans les valeurs

default

.

Une seule ligne

Un token de slot tient sur une seule ligne. Aucun saut de ligne ne doit y être présent.

Les dix types de slot

Type text — Texte court

Champ d'une seule ligne, sans mise en forme.

<h1>{{slot:hero_title|type=text|default=Bienvenue|label=Titre principal|maxlength=80}}</h1>
  • Interface : champ de saisie simple.
  • Idéal pour : titres, libellés, boutons d'appel à l'action, copyright.
  • Compteur de caractères affiché si maxlength est défini.
Type textarea — Texte long brut

Multi-lignes, sans mise en forme HTML.

<p class="lead">{{slot:hero_lead|type=textarea|default=Une accroche.|label=Accroche|maxlength=300}}</p>
  • Interface : zone de texte multi-lignes.
  • Les retours à la ligne sont automatiquement convertis en balises <br> au rendu.
  • Idéal pour : accroches, paragraphes simples.
Type richtext — Texte riche WYSIWYG

Mise en forme complète via CKEditor.

<div class="post-body">
    {{slot:post_body|type=richtext|default=<p>Contenu de l'article.</p>|label=Corps de l'article}}
</div>
  • Interface : éditeur CKEditor (Format, gras, italique, listes, liens, couleurs, alignement, etc.).
  • Idéal pour : corps d'articles, descriptions longues, conditions générales.
  • La valeur stockée contient du HTML (<p>, <strong>, etc.).
Type image — Média image
<img src="{{slot:hero_image|type=image|default=/medias/hero.jpg|label=Image hero}}" alt="...">
  • Interface : champ texte, bouton de sélection dans la bibliothèque, bouton de suppression et vignette d'aperçu.
  • Stocke soit une URL absolue, soit un shortcode {{media:ref=X.url}}.
  • Non traduisible par défaut : la même image est servie dans toutes les langues.
Type url — Lien
<a href="{{slot:hero_cta_url|type=url|default=/contact|label=URL du bouton}}">...</a>
  • Interface : champ texte avec validation URL légère.
  • Idéal pour : URL de bouton, liens vers les réseaux sociaux, URL de partage.
Type icon — Icône FontAwesome
{{slot:feature_1_icon|type=icon|default=fa-solid fa-rocket|label=Icône feature 1}}
  • Interface : champ classe, sélecteur de couleur, vingt icônes proposées en accès rapide, aperçu en direct.
  • Stockage en JSON : {"class":"fa-solid fa-star","color":"#fbbf24"}.
  • Rendu : <i class="fa-solid fa-star" style="color:#fbbf24"></i>.
  • Sécurisé : liste blanche sur la classe (a-zA-Z0-9_-) et expression régulière hexadécimale sur la couleur.
Type color — Couleur
<section style="background-color:{{slot:section_bg|type=color|default=#19052d|label=Couleur de fond}}">
  • Interface : sélecteur de couleur HTML5, champ hexadécimal, bouton de retour à la valeur par défaut.
  • Format strict : #RRGGBB ou #RRGGBBAA (avec transparence).
  • Non traduisible.
Type number — Nombre
<span class="stat">{{slot:stats_clients|type=number|default=42|label=Nombre de clients}}</span>
Type bool — Booléen
<?php if ('{{slot:hero_show_badge|type=bool|default=1|label=Afficher le badge}}'): ?>
    <span class="badge">Nouveau</span>
<?php endif; ?>
  • Interface : case à cocher.
  • Valeur : 0 ou 1.
Type select — Liste déroulante
<section class="hero hero-{{slot:hero_layout|type=select|options=light,dark,gradient|default=light|label=Style du hero}}">
  • Interface : menu déroulant.
  • Les valeurs disponibles sont définies dans options (CSV obligatoire).

Valeurs par défaut spéciales

default=@lang:KEY — Résolution via les fichiers de langue

Lorsque votre site utilise déjà des fichiers .lang Dolibarr (cas typique pour les sites multilingues existants), vous pouvez réutiliser les clés au lieu de les dupliquer dans les slots :

<h1>{{slot:hero_title|type=text|default=@lang:HeroTitle|label=Titre du hero}}</h1>

Au moment du rendu, le module résout via $langs->trans('HeroTitle') selon la langue du visiteur. Les fichiers .lang du site présents dans DOL_DATA_ROOT/<entity>/website/<ref>/langs/ sont chargés automatiquement.

Cas d'usage — Migration progressive d'un site existant : vous conservez vos fichiers .lang en l'état, vous ajoutez les slots, et le client peut soit éditer dans le Studio (surcharge), soit conserver la traduction du .lang (canonique).

Récapitulatif des types et de leur traduisibilité

Type

Interface

Traduisible

text

Champ de saisie

Oui

textarea

Zone de texte

Oui

richtext

CKEditor

Oui

image

Sélecteur de média

Non

url

Champ de saisie

Non

icon

Classe et sélecteur de couleur

Non

color

Sélecteur de couleur

Non

number

Champ numérique

Oui (rare)

bool

Case à cocher

Non

select

Menu déroulant

Non

Pièges fréquents

Slots dans des attributs JSON intégrés — Si vous avez du JSON intégré dans une balise (par exemple data-config="{...}"), n'y placez pas de slot. Les doubles accolades sont aussi un délimiteur Mustache et risquent de casser les bibliothèques JavaScript qui parseraient ce JSON.

Identifiant trop long — La limite est de 64 caractères. Au-delà, le scanner rejette silencieusement, ce que met en évidence l'option --lint.

Espaces autour des = — Le scanner rejette type = text. Utilisez toujours type=text.

Caractère pipe dans une valeur — default=A|B casse l'analyseur. Utilisez une autre séparation, ou laissez default vide et saisissez la valeur via le Studio.

Récapitulatif

Vous savez désormais :

  • La syntaxe complète d'un token de slot.
  • Les dix types disponibles et leurs interfaces respectives.
  • La résolution @lang:KEY pour réutiliser les fichiers .lang Dolibarr.
  • Quels types sont traduisibles ou non.
  • Les pièges syntaxiques fréquents.

Le chapitre suivant aborde les shortcodes, qui injectent des données Dolibarr dans le HTML.

Back to top