Skip to main content

La grammaire des slots en détail

📚 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 sous la main quand vous annotez 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 sauf name et type sont optionnels. L'ordre est libre. Le séparateur est le pipe |.

📜 Règles syntaxiques

Règle

Détail

Identifiant

[a-z0-9_]+

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

Unicité

Unique par page. Deux slots avec le même nom dans la même page = warning au scan.

Pas d'espaces

Pas d'espace de chaque côté du

=

. Pas d'espace dans les noms d'attributs.

Échappement

Le pipe

|

dans une valeur n'est pas supporté. Évitez-le dans les

default

.

Multi-lignes

Un token slot tient sur une seule ligne. Pas de saut de ligne à l'intérieur.

🎨 Les 10 types de slot

1️⃣ text — Texte court

Champ d'une ligne, sans formatage.

<h1>{{slot:hero_title|type=text|default=Bienvenue|label=Titre principal|maxlength=80}}</h1>
  • UI Studio : input simple.
  • Idéal pour : titres, libellés, CTA, copyright.
  • Compteur si maxlength défini.

2️⃣ textarea — Texte long brut

Multi-lignes, sans formatage HTML.

<p class="lead">{{slot:hero_lead|type=textarea|default=Une accroche.|label=Accroche|maxlength=300}}</p>
  • UI Studio : textarea.
  • Les \n deviennent <br> automatiquement au rendu.
  • Idéal pour : accroches, courts paragraphes simples.

3️⃣ 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>
  • UI Studio : CKEditor (Format, Bold/Italic, Listes, Liens, Couleurs, Alignement, …).
  • Idéal pour : corps d'articles, descriptions longues, conditions générales.
  • La valeur stockée contient du HTML (<p>, <strong>, etc.).

4️⃣ image — Média image

<img src="{{slot:hero_image|type=image|default=/medias/hero.jpg|label=Image hero}}" alt="...">
  • UI Studio : input texte + bouton picker média + bouton retirer + vignette.
  • Stocke soit une URL absolue, soit un shortcode {{media:ref=X.url}}.
  • Non traduisible par défaut (la même image dans toutes les langues).

5️⃣ url — Lien

<a href="{{slot:hero_cta_url|type=url|default=/contact|label=URL du bouton}}">...</a>
  • UI Studio : champ texte avec validation URL légère.
  • Idéal pour : URL de bouton, liens sociaux, URLs de partage.

6️⃣ icon — Icône FontAwesome

{{slot:feature_1_icon|type=icon|default=fa-solid fa-rocket|label=Icône feature 1}}
  • UI Studio : input classe + color picker + 20 icônes rapides + preview live.
  • Stockage JSON : {"class":"fa-solid fa-star","color":"#fbbf24"}.
  • Rendu : <i class="fa-solid fa-star" style="color:#fbbf24"></i>.
  • Sanitisé : whitelist sur la classe (a-zA-Z0-9_-) et regex hexadécimal.

7️⃣ color — Couleur

<section style="background-color:{{slot:section_bg|type=color|default=#19052d|label=Couleur de fond}}">
  • UI Studio : color picker HTML5 + champ hex texte + bouton « Défaut ».
  • Format strict : #RRGGBB ou #RRGGBBAA (transparence).
  • Non traduisible.

8️⃣ number — Nombre

<span class="stat">{{slot:stats_clients|type=number|default=42|label=Nombre de clients}}</span>

9️⃣ bool — Booléen

<?php if ('{{slot:hero_show_badge|type=bool|default=1|label=Afficher le badge}}'): ?>
    <span class="badge">Nouveau</span>
<?php endif; ?>
  • UI Studio : checkbox.
  • Valeur : 0 ou 1.

🔟 select — Liste déroulante

<section class="hero hero-{{slot:hero_layout|type=select|options=light,dark,gradient|default=light|label=Style du hero}}">
  • UI Studio : dropdown.
  • Valeur dans options (CSV obligatoire).

🎁 Valeurs par défaut spéciales

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

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

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

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

✅ Cas d'usage — Migration progressive d'un site existant : vous gardez vos .lang tels quels, vous ajoutez les slots, le client peut soit éditer dans le Studio (override) soit garder la traduction du .lang (canonique).

📊 Résumé des types et de leur traduisibilité

Type

UI

Traduisible

text

Input

✅ Oui

textarea

Textarea

✅ Oui

richtext

CKEditor

✅ Oui

image

Picker média

❌ Non

url

Input

❌ Non

icon

Classe + color picker

❌ Non

color

Color picker

❌ Non

number

Input numérique

⚠️ Oui (rare)

bool

Checkbox

❌ Non

select

Dropdown

❌ Non

⚠️ Pièges fréquents

⚠️ Slots dans des attributs JSON inline — Si vous avez du JSON inline dans une balise (data-config="{...}"), n'y mettez pas de slot. Les double accolades {{ sont aussi un délimiteur Mustache et risquent de casser les libs JS qui parseraient le JSON.

⚠️ Identifiant trop long — La limite est 64 caractères. Au-delà, le scanner rejette silencieusement (visible avec --lint).

⚠️ Espaces autour des = — Le scanner refuse type = text. Toujours type=text.

⚠️ Caractère pipe dans une valeur — default=A|B casse le parser. Utilisez une autre séparation ou un default vide + valeur via le Studio.

📋 Récapitulatif

✅ Vous savez maintenant :

  • La syntaxe complète d'un token slot.
  • Les 10 types disponibles et leurs UIs 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.

Au prochain chapitre, on aborde les shortcodes qui injectent des données Dolibarr dans le HTML.

Back to top