# 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:|type=|default=|label=|group=
|help=|maxlength=|options=}} ``` 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. ```

{{slot:hero_title|type=text|default=Bienvenue|label=Titre principal|maxlength=80}}

``` - 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. ```

{{slot:hero_lead|type=textarea|default=Une accroche.|label=Accroche|maxlength=300}}

``` - Interface : zone de texte multi-lignes. - Les retours à la ligne sont automatiquement convertis en balises `
` au rendu. - Idéal pour : accroches, paragraphes simples. ##### **Type richtext — Texte riche WYSIWYG** Mise en forme complète via CKEditor. ```
{{slot:post_body|type=richtext|default=

Contenu de l'article.

|label=Corps de l'article}}
``` - 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 (`

`, ``, etc.). ##### **Type image — Média image** ``` ... ``` - 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** ``` ... ``` - 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 : ``. - Sécurisé : liste blanche sur la classe (a-zA-Z0-9\_-) et expression régulière hexadécimale sur la couleur. ##### **Type color — Couleur** ```

``` - 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** ``` {{slot:stats_clients|type=number|default=42|label=Nombre de clients}} ``` ##### **Type bool — Booléen** ``` Nouveau ``` - Interface : case à cocher. - Valeur : 0 ou 1. ##### **Type select — Liste déroulante** ```
``` - 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 : ```

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

``` 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//website//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.