# PARTIE IV — Pour le développeur intégrateur

# CHAPITRE 17 — Préparer un site Dolibarr Website

Avant de pouvoir éditer un site via le module, ce site doit exister côté Dolibarr Website. Ce chapitre s'adresse au développeur qui démarre un nouveau projet : créer le site, le câbler proprement, et préparer le terrain pour le Studio.

### <span style="color: rgb(35, 111, 161);">Étape 1 — Créer le site dans Dolibarr Website</span>

1. Connectez-vous à Dolibarr en tant qu'administrateur.
2. Rendez-vous dans Accueil → Sites web.
3. <span style="white-space: pre-wrap;">Cliquez sur </span>**Nouveau site**.
4. Renseignez les informations suivantes :
    - **Référence**<span style="white-space: pre-wrap;"> : identifiant court sans espace, par exemple </span>`<span class="editor-theme-code">monsite</span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code">keaticweb</span>`. C'est l'identifiant interne, utilisé partout (URLs des wrappers, dossiers de données, constantes de configuration).
    - **Description**<span style="white-space: pre-wrap;"> : libellé facultatif.</span>
    - **Virtualhost principal**<span style="white-space: pre-wrap;"> : URL publique, par exemple </span>`<span class="editor-theme-code">https://monsite.com</span>`.
    - **Langue principale**<span style="white-space: pre-wrap;"> : code de la locale, par exemple </span>`<span class="editor-theme-code">fr_FR</span>`.
    - **Autres langues**<span style="white-space: pre-wrap;"> : valeurs séparées par des virgules, par exemple </span>`<span class="editor-theme-code">en_US,de_DE,es_ES</span>`.
5. Enregistrez.

<p class="callout info">**Convention de référence —**<span style="white-space: pre-wrap;"> Privilégiez un identifiant court et stable. Cette référence apparaîtra dans les chemins de fichiers, les URLs internes et les constantes de configuration. La modifier ultérieurement nécessite plusieurs ajustements.</span></p>

### <span style="color: rgb(35, 111, 161);">Étape 2 — Configurer le virtualhost Apache</span>

Le module Website ne configure pas Apache pour vous. Vous devez créer un VirtualHost qui pointe sur le docroot du site.

##### **Arborescence type**

```
/var/www/monsite/                           # docroot Apache du site
├── index.php                                # wrapper page d'accueil
├── <alias>.php                              # autres wrappers générés
├── master.inc.php                           # bootstrap (inclut DOL_DOCUMENT_ROOT)
├── medias  -> lien symbolique vers DOL_DATA_ROOT/<entity>/medias/
└── ...

DOL_DATA_ROOT/<entity>/website/monsite/      # dossier de données du site
├── page1.tpl.php                            # gabarits des pages
├── page2.tpl.php
├── ...
└── htmlheader.html                          # en-tête commun éventuel
```

##### **Exemple de VirtualHost minimal**

```
<VirtualHost *:443>
    ServerName monsite.com
    DocumentRoot /var/www/monsite

    SSLEngine on
    SSLCertificateFile      /etc/letsencrypt/live/monsite.com/fullchain.pem
    SSLCertificateKeyFile   /etc/letsencrypt/live/monsite.com/privkey.pem

    <Directory /var/www/monsite>
        Options FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    # PHP-FPM dédié recommandé
    <FilesMatch \.php$>
        SetHandler "proxy:unix:/run/php/php8.2-fpm.monsite.sock|fcgi://localhost"
    </FilesMatch>
</VirtualHost>
```

<p class="callout info">**Note —**<span style="white-space: pre-wrap;"> Un pool PHP-FPM dédié est recommandé pour isoler les performances et les variables d'environnement par site. Le pool peut tourner sous un utilisateur spécifique pour faciliter la gestion des permissions.</span></p>

### <span style="color: rgb(35, 111, 161);">Étape 3 — Le lien symbolique medias</span>

Pour que les images téléversées soient servies directement par Apache (mode média « native »), il faut un lien symbolique :

```
cd /var/www/monsite
ln -sfn /mnt/data/dolibarr/<entity>/medias medias
ls -la medias  # doit pointer sur le dossier de données Dolibarr
```

<p class="callout info">**Conseil —**<span style="white-space: pre-wrap;"> Si vous ne pouvez pas créer ce lien symbolique, basculez le site en mode média </span>**module**<span style="white-space: pre-wrap;"> dans la configuration du module. Les images seront servies via </span>`<span class="editor-theme-code">document.php</span>`, avec un coût de performance modéré.</p>

### <span style="color: rgb(35, 111, 161);">Étape 4 — Le master.inc.php multicompany</span>

<span style="white-space: pre-wrap;">Si votre installation Dolibarr fonctionne en multicompany, le fichier </span>`<span class="editor-theme-code">master.inc.php</span>`<span style="white-space: pre-wrap;"> du site doit définir </span>`<span class="editor-theme-code">DOLENTITY</span>`<span style="white-space: pre-wrap;"> avant le chargement :</span>

```
<?php
// /var/www/monsite/master.inc.php
define('DOLENTITY', 2);   // l'entity correspondant au client
require_once '/var/www/dolibarr/htdocs/master.inc.php';
```

<p class="callout warning">**Avertissement —**<span style="white-space: pre-wrap;"> Sur une instance multicompany sans </span>`<span class="editor-theme-code">DOLENTITY</span>`, le site renverra une erreur 503 ou affichera les données de la mauvaise entity. C'est l'erreur la plus fréquemment rencontrée lors de la mise en service.</p>

### <span style="color: rgb(35, 111, 161);">Étape 5 — Créer la page d'accueil</span>

Toujours dans le module Website Dolibarr :

1. Sélectionnez votre site.
2. <span style="white-space: pre-wrap;">Cliquez sur </span>**Nouvelle page**.
3. Renseignez :
    - **Page URL**<span style="white-space: pre-wrap;"> : </span>`<span class="editor-theme-code">home</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">index</span>`<span style="white-space: pre-wrap;"> ou autre.</span>
    - **Title**<span style="white-space: pre-wrap;"> : Accueil.</span>
    - **Type container**<span style="white-space: pre-wrap;"> : </span>`<span class="editor-theme-code">page</span>`.
    - **Lang**<span style="white-space: pre-wrap;"> : </span>`<span class="editor-theme-code">fr_FR</span>`.
    - **Status**<span style="white-space: pre-wrap;"> : Brouillon (le passage à Publié interviendra plus tard).</span>
4. Enregistrez.
5. <span style="white-space: pre-wrap;">Dolibarr crée automatiquement les fichiers </span>`<span class="editor-theme-code">/var/www/monsite/home.php</span>`<span style="white-space: pre-wrap;"> et </span>`<span class="editor-theme-code">page<N>.tpl.php</span>`.

### <span style="color: rgb(35, 111, 161);">Étape 6 — Activer le site dans le module</span>

La procédure complète est détaillée au Chapitre 7. En résumé :

1. Outils → InfraSStudio → Configuration.
2. Cochez votre site dans la liste.
3. Choisissez le mode média (**native**<span style="white-space: pre-wrap;"> recommandé).</span>
4. Enregistrez.

### <span style="color: rgb(35, 111, 161);">Étape 7 — Annoter les premières pages avec des slots</span>

<span style="white-space: pre-wrap;">Cette étape fait l'objet du Chapitre 18. En quelques mots : modifiez le fichier </span>`<span class="editor-theme-code">page<N>.tpl.php</span>`<span style="white-space: pre-wrap;"> pour ajouter des tokens </span>`<span class="editor-theme-code">{{slot:nom|type=...}}</span>`<span style="white-space: pre-wrap;"> aux endroits que vous souhaitez rendre éditables.</span>

### <span style="color: rgb(35, 111, 161);">Étape 8 — Vérifier avec la page Diagnostic</span>

Avant de livrer le site au client, lancez le diagnostic (Outils → InfraSStudio → Diagnostic) :

- Tous les voyants verts dans Environnement, Schéma SQL, Stockage et Intégration Dolibarr.
- Le site géré apparaît dans la section Sites avec docroot résolu, mode média correct et dossier de données accessible en écriture.

### <span style="color: rgb(35, 111, 161);">Récapitulatif</span>

**Votre site est prêt si :**

- Le site est créé dans Dolibarr Website (référence, virtualhost, langues).
- Le VirtualHost Apache pointe sur le bon docroot.
- <span style="white-space: pre-wrap;">Le lien symbolique </span>`<span class="editor-theme-code">medias</span>`<span style="white-space: pre-wrap;"> est en place (mode native), ou la constante </span>`<span class="editor-theme-code">INFRASSTUDIO_SITE_<id>_MEDIA_MODE=module</span>`<span style="white-space: pre-wrap;"> est définie.</span>
- <span style="white-space: pre-wrap;">Le fichier </span>`<span class="editor-theme-code">master.inc.php</span>`<span style="white-space: pre-wrap;"> définit </span>`<span class="editor-theme-code">DOLENTITY</span>`<span style="white-space: pre-wrap;"> en multicompany.</span>
- Au moins une page existe (l'accueil).
- Le site est coché dans la configuration du module.
- La page Diagnostic est entièrement verte.

Le chapitre suivant aborde l'annotation des templates avec des slots.

# CHAPITRE 18 — Annoter un template avec des slots

Le slot est l'unité de base du module. Ce chapitre vous montre comment transformer un HTML statique en HTML annoté, prêt à être édité par le client. Il s'agit de l'opération la plus fréquente dans votre travail d'intégrateur.

### <span style="color: rgb(35, 111, 161);">Le principe en deux phrases</span>

1. Vous écrivez votre HTML normalement, comme vous le feriez sans le module.
2. <span style="white-space: pre-wrap;">Aux endroits que vous voulez rendre éditables, vous remplacez le contenu en dur par un token </span>`<span class="editor-theme-code">{{slot:...}}</span>`.

C'est tout. Le module se charge du reste : détection automatique, persistance, rendu, interface d'édition.

### <span style="color: rgb(35, 111, 161);">Premier exemple complet</span>

##### **Avant — page non éditable**

```
<section class="hero">
    <h1>Bienvenue chez Keatic</h1>
    <p>Votre partenaire numérique de confiance depuis 2010.</p>
    <a href="/contact" class="btn">Nous contacter</a>
</section>
```

##### **Après — page éditable via le Studio**

```
<section class="hero">
    <h1>{{slot:hero_title|type=text|default=Bienvenue chez Keatic|label=Titre du hero|group=hero}}</h1>
    <p>{{slot:hero_lead|type=textarea|default=Votre partenaire numérique de confiance depuis 2010.|label=Accroche|group=hero}}</p>
    <a href="{{slot:hero_cta_url|type=url|default=/contact|label=URL du bouton|group=hero}}" class="btn">
        {{slot:hero_cta_label|type=text|default=Nous contacter|label=Libellé du bouton|group=hero}}
    </a>
</section>
```

<p class="callout success">**Résultat —**<span style="white-space: pre-wrap;"> Le client voit dans le Studio un panneau « Hero » comportant quatre champs (titre, accroche, URL du bouton, libellé du bouton). Aucun HTML à modifier de son côté.</span></p>

### <span style="color: rgb(35, 111, 161);">Anatomie d'un token de slot</span>

```
{{slot:<identifiant>|type=<type>|attribut1=valeur1|attribut2=valeur2}}
```

<table id="bkmrk-%C3%89l%C3%A9mentobligatoirede" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Élément

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Obligatoire

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Description

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">{{slot:</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Oui

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Préfixe fixe qui déclare un slot.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Identifiant

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Oui

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Unique par page. Caractères acceptés : minuscules, chiffres, tiret bas. 64 caractères maximum.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">type=</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Oui

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">text, textarea, richtext, image, url, number, select, bool, icon, color.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">default=</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Recommandé

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Valeur de repli si le slot n'est pas encore édité.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">label=</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Recommandé

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Libellé affiché à l'éditeur dans le Studio.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">group=</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Facultatif

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Regroupe les slots dans une section de l'interface.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">help=</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Facultatif

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Aide affichée sous le champ.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">maxlength=</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Facultatif

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Limite de caractères pour text et textarea.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">options=</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Si type=select

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Liste CSV des valeurs possibles.

</td></tr></tbody></table>

**Conseil —**<span style="white-space: pre-wrap;"> La grammaire complète est détaillée au Chapitre 19.</span>

### <span style="color: rgb(35, 111, 161);">Où placer un slot</span>

Un slot peut être placé à de nombreux endroits dans votre HTML.

##### **Dans le contenu d'une balise (cas le plus fréquent)**

```
<h1>{{slot:title|type=text|default=Bienvenue}}</h1>
```

##### **Dans un attribut HTML**

```
<img src="{{slot:hero_image|type=image|default=/medias/hero.jpg}}" alt="...">
<a href="{{slot:cta_url|type=url|default=/contact}}">...</a>
<section style="background-color:{{slot:bg_color|type=color|default=#19052d}}">
```

##### **Dans une chaîne de classes CSS**

```
<i class="fa-solid {{slot:hero_icon|type=text|default=fa-rocket}}"></i>
```

<p class="callout warning">**À ne pas faire —**<span style="white-space: pre-wrap;"> Ne placez pas un slot dans un commentaire HTML, dans un bloc </span>`<span class="editor-theme-code"><script></span>`, ou dans du JSON intégré. Le scanner détecte tous les tokens et peut générer des slots fantômes.</p>

### <span style="color: rgb(35, 111, 161);">Convention de nommage des identifiants</span>

L'identifiant est libre, mais une convention claire facilite la maintenance.

##### **Schéma recommandé**

`<span class="editor-theme-code"><section>_<champ></span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code"><page>_<section>_<champ></span>`

<table id="bkmrk-bon%C3%80-%C3%A9viterhero_titl" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Bon

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">À éviter

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">hero_title</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">title</span>`

<span style="white-space: pre-wrap;"> (trop générique, risque de collision)</span>

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">features_grid_card_3_label</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">truc3</span>`

<span style="white-space: pre-wrap;"> (incompréhensible)</span>

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">footer_copyright</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">FooterCopyright</span>`

<span style="white-space: pre-wrap;"> (les majuscules sont rejetées par le scanner)</span>

</td></tr></tbody></table>

<p class="callout info">**Recommandé —**<span style="white-space: pre-wrap;"> Si votre site comporte cinq sections (hero, features, stats, testimonials, footer), préfixez tous vos slots par leur section. Le client retrouvera ainsi plus rapidement ce qu'il cherche dans le Studio.</span></p>

### <span style="color: rgb(35, 111, 161);">Utiliser le groupe pour structurer l'interface</span>

<span style="white-space: pre-wrap;">L'attribut </span>`<span class="editor-theme-code">group</span>`<span style="white-space: pre-wrap;"> détermine sous quelle section le slot apparaît dans le panneau « Contenu de la page » du Studio.</span>

```
{{slot:hero_title|type=text|group=hero|...}}
{{slot:hero_lead|type=textarea|group=hero|...}}
{{slot:hero_image|type=image|group=hero|...}}

{{slot:features_card_1_title|type=text|group=features|...}}
{{slot:features_card_2_title|type=text|group=features|...}}
{{slot:features_card_3_title|type=text|group=features|...}}

{{slot:footer_copyright|type=text|group=footer|...}}
```

Dans le Studio, ces slots seront regroupés visuellement sous trois sections : Hero, Features et Footer.

### <span style="color: rgb(35, 111, 161);">Le rescan après ajout</span>

<span style="white-space: pre-wrap;">Ajouter un slot dans un fichier </span>`<span class="editor-theme-code">tpl.php</span>`<span style="white-space: pre-wrap;"> ne suffit pas : le module doit le détecter et l'enregistrer en base. Pour cela, lancez un rescan.</span>

##### **Méthode A — Via l'interface Studio**

1. Outils → InfraSStudio → Contenu des pages.
2. Sélectionnez votre site.
3. <span style="white-space: pre-wrap;">Cliquez sur </span>**Rescanner**<span style="white-space: pre-wrap;"> en haut.</span>
4. <span style="white-space: pre-wrap;">Le module parcourt tous les fichiers </span>`<span class="editor-theme-code">tpl.php</span>`<span style="white-space: pre-wrap;"> et synchronise les slots.</span>

##### **Méthode B — En ligne de commande**

```
php htdocs/custom/infrasstudio/scripts/rescan_slots.php <ref-du-site> --entity=<N>
```

Sortie typique :

```
Rescanning website #1 — monsite (entity 2)
Pages scanned   : 22
Slots added     : 3
Slots updated   : 40
Slots orphaned  : 0
```

**Mode de validation —**<span style="white-space: pre-wrap;"> Ajoutez l'option </span>`<span class="editor-theme-code">--lint</span>`<span style="white-space: pre-wrap;"> pour détecter les erreurs de syntaxe avant de les valider :</span>  
`<span class="editor-theme-code">php rescan_slots.php <ref> --lint</span>`  
Le code de sortie est:

- <span style="white-space: pre-wrap;"> 0 en l'absence d'erreur</span>
- 1 en présence d'avertissements
- <span style="white-space: pre-wrap;"> 2 en cas d'erreurs.</span>

<span style="white-space: pre-wrap;"> Cette commande peut être intégrée dans un crochet de pré-commit.</span>

### <span style="color: rgb(35, 111, 161);">Slots orphelins</span>

<span style="white-space: pre-wrap;">Lorsque vous supprimez un slot d'un fichier </span>`<span class="editor-theme-code">tpl.php</span>`, son enregistrement en base passe au statut « orphelin ». Le module le conserve pendant 30 jours avant de le supprimer automatiquement (via une tâche planifiée).

Cette politique présente un avantage : si vous restaurez le slot dans le HTML pendant cette période, sa valeur précédente est récupérée.

<p class="callout info">**Note —**<span style="white-space: pre-wrap;"> Pour forcer la purge immédiate des slots orphelins :</span>  
`<span class="editor-theme-code">php rescan_slots.php <ref> --purge-orphans</span>`</p>

### <span style="color: rgb(35, 111, 161);">Liste de contrôle d'annotation</span>

**Avant de livrer une page annotée :**

- <span style="white-space: pre-wrap;">Chaque slot possède un </span>`<span class="editor-theme-code">type</span>`<span style="white-space: pre-wrap;"> explicite.</span>
- <span style="white-space: pre-wrap;">Chaque slot possède une valeur </span>`<span class="editor-theme-code">default</span>`, garantissant la lisibilité de la page si la base venait à se vider.
- <span style="white-space: pre-wrap;">Chaque slot possède un </span>`<span class="editor-theme-code">label</span>`<span style="white-space: pre-wrap;"> en français clair, destiné à l'éditeur.</span>
- <span style="white-space: pre-wrap;">Les slots sont regroupés par section avec </span>`<span class="editor-theme-code">group</span>`.
- <span style="white-space: pre-wrap;">Les identifiants suivent la convention </span>`<span class="editor-theme-code"><section>_<champ></span>`.
- Le rescan a été lancé sans avertissement ni erreur.
- Vous avez ouvert la page dans le Studio et vérifié la présence de tous les slots.

Le chapitre suivant détaille la grammaire complète des slots, avec tous les types et leurs comportements.

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

### <span style="color: rgb(35, 111, 161);">Format général</span>

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

<span style="white-space: pre-wrap;">Tous les attributs, à l'exception de </span>`<span class="editor-theme-code">name</span>`<span style="white-space: pre-wrap;"> et </span>`<span class="editor-theme-code">type</span>`, sont facultatifs. L'ordre est libre. Le séparateur est le caractère pipe.

### <span style="color: rgb(35, 111, 161);">Règles syntaxiques</span>

<table id="bkmrk-r%C3%A8gled%C3%A9tailidentifia" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Règle

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Détail

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Identifiant**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">[a-z0-9_]+</span>`

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

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Unicité**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Unique par page. Deux slots avec le même nom sur la même page produisent un avertissement au scan.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Pas d'espaces**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Aucun espace de part et d'autre du signe </span>

`<span class="editor-theme-code">=</span>`

. Aucun espace dans les noms d'attributs.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Échappement**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Le pipe à l'intérieur d'une valeur n'est pas pris en charge. Évitez-le dans les valeurs </span>

`<span class="editor-theme-code">default</span>`

.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Une seule ligne**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Un token de slot tient sur une seule ligne. Aucun saut de ligne ne doit y être présent.

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Les dix types de slot</span>

##### **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.
- <span style="white-space: pre-wrap;">Compteur de caractères affiché si </span>`<span class="editor-theme-code">maxlength</span>`<span style="white-space: pre-wrap;"> est défini.</span>

##### **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.
- <span style="white-space: pre-wrap;">Les retours à la ligne sont automatiquement convertis en balises </span>`<span class="editor-theme-code"><br></span>`<span style="white-space: pre-wrap;"> au rendu.</span>
- 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 (`<span class="editor-theme-code"><p></span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code"><strong></span>`, 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.
- <span style="white-space: pre-wrap;">Stocke soit une URL absolue, soit un shortcode </span>`<span class="editor-theme-code">{{media:ref=X.url}}</span>`.
- 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.
- <span style="white-space: pre-wrap;">Stockage en JSON : </span>`<span class="editor-theme-code">{"class":"fa-solid fa-star","color":"#fbbf24"}</span>`.
- <span style="white-space: pre-wrap;">Rendu : </span>`<span class="editor-theme-code"><i class="fa-solid fa-star" style="color:#fbbf24"></i></span>`.
- 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.
- <span style="white-space: pre-wrap;">Format strict : </span>`<span class="editor-theme-code">#RRGGBB</span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code">#RRGGBBAA</span>`<span style="white-space: pre-wrap;"> (avec transparence).</span>
- 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.
- <span style="white-space: pre-wrap;">Les valeurs disponibles sont définies dans </span>`<span class="editor-theme-code">options</span>`<span style="white-space: pre-wrap;"> (CSV obligatoire).</span>

### <span style="color: rgb(35, 111, 161);">Valeurs par défaut spéciales</span>

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

<span style="white-space: pre-wrap;">Lorsque votre site utilise déjà des fichiers </span>`<span class="editor-theme-code">.lang</span>`<span style="white-space: pre-wrap;"> Dolibarr (cas typique pour les sites multilingues existants), vous pouvez réutiliser les clés au lieu de les dupliquer dans les slots :</span>

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

<span style="white-space: pre-wrap;">Au moment du rendu, le module résout via </span>`<span class="editor-theme-code">$langs->trans('HeroTitle')</span>`<span style="white-space: pre-wrap;"> selon la langue du visiteur. Les fichiers </span>`<span class="editor-theme-code">.lang</span>`<span style="white-space: pre-wrap;"> du site présents dans </span>`<span class="editor-theme-code">DOL_DATA_ROOT/<entity>/website/<ref>/langs/</span>`<span style="white-space: pre-wrap;"> sont chargés automatiquement.</span>

<p class="callout info">**Cas d'usage —**<span style="white-space: pre-wrap;"> Migration progressive d'un site existant : vous conservez vos fichiers </span>`<span class="editor-theme-code">.lang</span>`<span style="white-space: pre-wrap;"> en l'état, vous ajoutez les slots, et le client peut soit éditer dans le Studio (surcharge), soit conserver la traduction du </span>`<span class="editor-theme-code">.lang</span>`<span style="white-space: pre-wrap;"> (canonique).</span></p>

### <span style="color: rgb(35, 111, 161);">Récapitulatif des types et de leur traduisibilité</span>

<table id="bkmrk-typeinterfacetraduis" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Type

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Interface

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Traduisible

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">text</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Champ de saisie

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Oui

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">textarea</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Zone de texte

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Oui

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">richtext</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">CKEditor

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Oui

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">image</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Sélecteur de média

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Non

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">url</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Champ de saisie

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Non

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">icon</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Classe et sélecteur de couleur

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Non

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">color</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Sélecteur de couleur

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Non

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">number</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Champ numérique

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Oui (rare)

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">bool</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Case à cocher

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Non

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">select</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Menu déroulant

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Non

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Pièges fréquents</span>

**Slots dans des attributs JSON intégrés —**<span style="white-space: pre-wrap;"> Si vous avez du JSON intégré dans une balise (par exemple </span>`<span class="editor-theme-code">data-config="{...}"</span>`), 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 —**<span style="white-space: pre-wrap;"> La limite est de 64 caractères. Au-delà, le scanner rejette silencieusement, ce que met en évidence l'option </span>`<span class="editor-theme-code">--lint</span>`.

**Espaces autour des = —**<span style="white-space: pre-wrap;"> Le scanner rejette </span>`<span class="editor-theme-code">type = text</span>`<span style="white-space: pre-wrap;">. Utilisez toujours </span>`<span class="editor-theme-code">type=text</span>`.

**Caractère pipe dans une valeur —**<span style="white-space: pre-wrap;"> </span>`<span class="editor-theme-code">default=A|B</span>`<span style="white-space: pre-wrap;"> casse l'analyseur. Utilisez une autre séparation, ou laissez </span>`<span class="editor-theme-code">default</span>`<span style="white-space: pre-wrap;"> vide et saisissez la valeur via le Studio.</span>

### <span style="color: rgb(35, 111, 161);">Récapitulatif</span>

**Vous savez désormais :**

- La syntaxe complète d'un token de slot.
- Les dix types disponibles et leurs interfaces respectives.
- <span style="white-space: pre-wrap;">La résolution </span>`<span class="editor-theme-code">@lang:KEY</span>`<span style="white-space: pre-wrap;"> pour réutiliser les fichiers .lang Dolibarr.</span>
- 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.

### <span style="color: rgb(35, 111, 161);">Sections masquables et bloc-éditing : {{if\_section:UID}} (depuis 18.42/18.47)</span>

Enveloppez une section complète pour la rendre pilotable depuis le Studio (barre de contrôle : déplacer, masquer, dupliquer, supprimer, insérer) :

<span class="editor-theme-code">{{if\_section:hero}}&lt;section class="hero"&gt;{{slot:hero\_visible|type=bool|default=1|label=Afficher la section Hero|group=Affichage}} … &lt;/section&gt;{{/if\_section}}</span>

- sémantique **inverse** de <span class="editor-theme-code">if\_slot</span> : la section est **visible par défaut** ; elle n'est retirée du rendu public que si le slot conventionné <span class="editor-theme-code">&lt;uid&gt;\_visible</span> (type bool) résout explicitement à 0 ;
- en aperçu, la section n'est jamais retirée : elle est estompée si masquée, et sa première balise reçoit le marqueur qui fait apparaître la barre de contrôle ;
- les blocs <span class="editor-theme-code">if\_section</span> peuvent s'imbriquer (carte masquable dans une section masquable) — le moteur évalue de l'intérieur vers l'extérieur ;
- un site jamais annoté reste rendu strictement à l'identique : l'annotation est purement additive.

### <span style="color: rgb(35, 111, 161);">Les champs groupés (convention de suffixes)</span>

Des slots d'une même page qui partagent une base et ne diffèrent que par un suffixe connu — <span class="editor-theme-code">\_label</span>, <span class="editor-theme-code">\_text</span>, <span class="editor-theme-code">\_title</span>, <span class="editor-theme-code">\_icon</span>, <span class="editor-theme-code">\_url</span>, <span class="editor-theme-code">\_style</span>, <span class="editor-theme-code">\_visible</span> — forment un **champ** édité dans un seul panneau. Exemple : <span class="editor-theme-code">nav\_solutions\_label</span> + <span class="editor-theme-code">nav\_solutions\_url</span> + <span class="editor-theme-code">nav\_solutions\_style</span> → cliquer le lien dans l'aperçu ouvre le texte, l'URL et le style ensemble. Aucun nouveau token, aucune migration : toute paire suivant la convention en bénéficie.

# CHAPITRE 20 — Insérer des données Dolibarr (shortcodes)

<span style="white-space: pre-wrap;">Les slots stockent du contenu éditable. Les </span>**shortcodes**, eux, affichent des données Dolibarr lues en direct (produits, catégories, informations société, médias). Ils sont résolus au moment du rendu, à chaque consultation de page.

### <span style="color: rgb(35, 111, 161);">Distinction entre slot et shortcode</span>

<table id="bkmrk-slotshortcodestocke-" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Slot

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Shortcode

</th></tr><tr><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Stocke du </span>

**contenu éditable**

<span style="white-space: pre-wrap;"> par le client.</span>

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Affiche des </span>

**données Dolibarr**

<span style="white-space: pre-wrap;"> lues en direct.</span>

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Persistance dans </span>

`<span class="editor-theme-code">llx_infrasstudio_slot</span>`

.

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">Aucune persistance — résolu à chaque requête.

</td></tr><tr><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Exemple : </span>

`<span class="editor-theme-code">{{slot:hero_title|type=text}}</span>`

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Exemple : </span>

`<span class="editor-theme-code">{{product:ref=supplyflow.label}}</span>`

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Syntaxe générale</span>

```
{{<namespace>:<sélecteur>.<champ>}}
```

- **namespace**<span style="white-space: pre-wrap;"> : la source de données (</span>`<span class="editor-theme-code">product</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">category</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">dict</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">mysoc</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">extrafield</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">media</span>`).
- **sélecteur**<span style="white-space: pre-wrap;"> : la manière d'identifier l'élément (le plus souvent </span>`<span class="editor-theme-code">ref=xxx</span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code">id=N</span>`).
- **champ**<span style="white-space: pre-wrap;"> : la donnée à extraire de l'élément.</span>

### <span style="color: rgb(35, 111, 161);">Namespace product</span>

<span style="white-space: pre-wrap;">Lit un produit dans la table </span>`<span class="editor-theme-code">llx_product</span>`.

```
<h2>{{product:ref=supplyflow-pro.label}}</h2>
<p>{{product:ref=supplyflow-pro.description}}</p>
<span class="price">{{product:ref=supplyflow-pro.price}} €</span>
<span>{{product:ref=supplyflow-pro.ef_tagline}}</span>
<img src="{{product:ref=supplyflow-pro.ef_hero_image}}" alt="...">
```

##### **Champs disponibles**

<table id="bkmrk-champsourcelabel%2C-de" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Champ

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Source

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">label</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">description</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">note</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Champs natifs (traduits selon la langue du visiteur via </span>

`<span class="editor-theme-code">llx_product_lang</span>`

)

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">price</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">price_ttc</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">cost_price</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Prix HT, TTC, coût (formaté selon la langue)

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">ref</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">tosell</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Référence, statut commercialisable

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">ef_<slug></span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Tout champ personnalisé (

`<span class="editor-theme-code">ef_tagline</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">ef_hero_image</span>`

, etc.)

</td></tr></tbody></table>

##### **Le marqueur $current**

<span style="white-space: pre-wrap;">Pour un même gabarit utilisé par plusieurs produits (par exemple </span>`<span class="editor-theme-code">solution-detail</span>`<span style="white-space: pre-wrap;"> servi par les wrappers </span>`<span class="editor-theme-code">solution-<ref>.php</span>`<span style="white-space: pre-wrap;">), utilisez </span>`<span class="editor-theme-code">ref=$current</span>`<span style="white-space: pre-wrap;"> :</span>

```
<h1>{{product:ref=$current.label}}</h1>
<p>{{product:ref=$current.ef_tagline}}</p>
```

<span style="white-space: pre-wrap;">Le module résout </span>`<span class="editor-theme-code">$current</span>`<span style="white-space: pre-wrap;"> via la variable globale </span>`<span class="editor-theme-code">$infrasstudio_current_product_ref</span>`, posée par le wrapper.

### <span style="color: rgb(35, 111, 161);">Namespace category</span>

<span style="white-space: pre-wrap;">Lit une catégorie dans la table </span>`<span class="editor-theme-code">llx_categorie</span>`.

```
<h3>{{category:id=5.label}}</h3>
<p>{{category:id=5.description}}</p>
```

### <span style="color: rgb(35, 111, 161);">Namespace dict</span>

Lit une entrée d'un dictionnaire Dolibarr (`<span class="editor-theme-code">c_country</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">c_currencies</span>`, etc.).

```
<span>{{dict:c_country.code=FR.label}}</span>
<span>{{dict:c_currencies.code_iso=EUR.label}}</span>
```

### <span style="color: rgb(35, 111, 161);">Namespace mysoc</span>

Lit les informations de la société courante (`<span class="editor-theme-code">$mysoc</span>`).

```
<footer>
    © {{mysoc.name}} — {{mysoc.address}}, {{mysoc.zip}} {{mysoc.town}}
    Tél : {{mysoc.phone}} — Courriel : {{mysoc.email}}
    SIRET {{mysoc.idprof2}} — TVA {{mysoc.tva_intra}}
</footer>
```

##### **Champs disponibles**

`<span class="editor-theme-code">name</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">address</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">zip</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">town</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">country_code</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">phone</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">fax</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">email</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">url</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">capital</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">tva_intra</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">idprof1</span>`<span style="white-space: pre-wrap;"> à </span>`<span class="editor-theme-code">idprof6</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">logo</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">logo_small</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">logo_squarred</span>`.

### <span style="color: rgb(35, 111, 161);">Namespace extrafield</span>

Lit un champ personnalisé d'un objet Dolibarr quelconque.

```
{{extrafield:table=product|ref=supplyflow.field=tagline}}
{{extrafield:table=societe|id=42|field=segment}}
{{extrafield:table=product|ref=$current|field=tagline}}
```

<span style="white-space: pre-wrap;">Plus générique que </span>`<span class="editor-theme-code">{{product:ref=X.ef_tagline}}</span>`<span style="white-space: pre-wrap;"> mais plus verbeux. À utiliser lorsque le namespace dédié n'existe pas (par exemple pour </span>`<span class="editor-theme-code">societe</span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code">contact</span>`).

### <span style="color: rgb(35, 111, 161);">Namespace media</span>

Lit un média de la bibliothèque du module (`<span class="editor-theme-code">llx_infrasstudio_media</span>`).

```
<img src="{{media:ref=hero-1.url}}" alt="{{media:ref=hero-1.alt}}">
<img src="{{media:ref=hero-1.thumb}}">
<img src="{{media:ref=hero-1.card}}">
<img src="{{media:ref=hero-1.wide}}">
```

##### **Champs disponibles**

<table id="bkmrk-champdescriptionurlu" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Champ

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Description

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">url</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">URL du fichier original

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">thumb</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Variante 200 × 200

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">card</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Variante 640 × 480

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">wide</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Variante 1600 × 1200

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">alt</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Texte alternatif (résolu selon la langue)

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">label</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">width</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">height</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Métadonnées

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Combiner shortcodes et slots</span>

Vous pouvez intégrer un shortcode dans la valeur par défaut d'un slot, ou dans le contenu d'un slot de type texte riche :

```
<!-- Shortcode dans le default d'un slot -->
<p>{{slot:greeting|type=text|default=Bienvenue chez {{mysoc.name}}}}</p>

<!-- Shortcode dans un slot richtext (l'éditeur peut le saisir librement) -->
<div>{{slot:long_intro|type=richtext|default=Notre équipe à {{mysoc.town}} vous accompagne.}}</div>
```

<p class="callout info">**Cas d'usage —**<span style="white-space: pre-wrap;"> Une page de remerciements après commande qui dit « Merci, votre commande sera livrée à... ». Le HTML reste statique côté gabarit, mais le rendu est personnalisé pour chaque visiteur.</span></p>

### <span style="color: rgb(35, 111, 161);">Étendre avec un namespace personnalisé</span>

<span style="white-space: pre-wrap;">Pour ajouter un namespace propre à votre projet, déposez un fichier dans </span>`<span class="editor-theme-code">htdocs/custom/infrasstudio/shortcodes/</span>`<span style="white-space: pre-wrap;"> :</span>

```
// shortcodes/myorg.shortcode.php
function infrasstudio_shortcode_myorg_resolve($args, $context)
{
    global $db;
    $id    = isset($args['id']) ? (int) $args['id'] : 0;
    $field = isset($args['_field']) ? $args['_field'] : 'name';
    if ($id <= 0) { return ''; }

    $sql = "SELECT name, sector FROM ".MAIN_DB_PREFIX."myorg WHERE rowid = ".$id;
    $resql = $db->query($sql);
    if (!$resql) { return ''; }
    $obj = $db->fetch_object($resql);
    $db->free($resql);
    return isset($obj->$field) ? (string) $obj->$field : '';
}
```

Utilisable dans n'importe quel gabarit :

```
<h2>{{myorg:id=12.name}}</h2>
<p>Secteur : {{myorg:id=12.sector}}</p>
```

### <span style="color: rgb(35, 111, 161);">Pièges et performance</span>

**Shortcode dans une boucle —**<span style="white-space: pre-wrap;"> Si vous résolvez cent fois le même shortcode dans une page, vous effectuez cent requêtes SQL. Mettez vos données en cache dans une variable locale avant la boucle, ou utilisez les fonctions natives Dolibarr (</span>`<span class="editor-theme-code">Product::fetch</span>`) en PHP.

**Shortcode introuvable —**<span style="white-space: pre-wrap;"> Si </span>`<span class="editor-theme-code">{{product:ref=inexistant.label}}</span>`<span style="white-space: pre-wrap;"> ne résout rien, le module retourne une chaîne vide silencieusement. Aucune erreur n'est affichée. Testez en local avant la livraison.</span>

**Shortcodes dans les attributs —**<span style="white-space: pre-wrap;"> Les shortcodes fonctionnent dans tous les contextes HTML, attributs compris : </span>`<span class="editor-theme-code"><img src="{{media:ref=X.url}}"></span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code"><a href="{{slot:cta_url|...}}"></span>`, etc.

### <span style="color: rgb(35, 111, 161);">Récapitulatif</span>

**Vous savez désormais :**

- Distinguer slots (contenu éditable) et shortcodes (données Dolibarr).
- Utiliser les six namespaces livrés (product, category, dict, mysoc, extrafield, media).
- <span style="white-space: pre-wrap;">Utiliser </span>`<span class="editor-theme-code">$current</span>`<span style="white-space: pre-wrap;"> dans les gabarits partagés entre plusieurs produits.</span>
- Combiner shortcodes et slots.
- <span style="white-space: pre-wrap;">Ajouter votre propre namespace via un fichier dans </span>`<span class="editor-theme-code">shortcodes/</span>`.
- Anticiper les pièges (boucles, valeurs absentes).

# CHAPITRE 21 — Gérer le multilingue (pages sœurs)

Dolibarr Website propose deux modèles multilingues différents. Identifier le modèle que vous utilisez est une étape préalable à toute écriture de code. Ce chapitre vous présente les deux options et la manière dont le module s'y intègre.

### <span style="color: rgb(35, 111, 161);">Les deux modèles multilingues</span>

<table id="bkmrk-mod%C3%A8lecaract%C3%A9ristiqu" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Modèle

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Caractéristique

</th></tr><tr><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">**A. Slot par langue**

<span style="white-space: pre-wrap;"> (recommandé)</span>

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">Un seul fichier tpl.php sert toutes les langues. Les slots disposent de surcharges par langue.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">**B. Pages sœurs**

<span style="white-space: pre-wrap;"> (legacy)</span>

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">Un fichier tpl.php par langue (

`<span class="editor-theme-code">about.php</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">about-en.php</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">about-de.php</span>`

). Modèle hérité des sites Dolibarr Website classiques.

</td></tr></tbody></table>

<p class="callout info">**Recommandé —**<span style="white-space: pre-wrap;"> Adoptez le modèle A pour tout nouveau site. Le modèle B reste pris en charge pour la migration progressive de sites existants. Le module fournit un outil de consolidation B vers A.</span></p>

### <span style="color: rgb(35, 111, 161);">Modèle A — Slot par langue (le standard moderne)</span>

##### **Fonctionnement**

<span style="white-space: pre-wrap;">Une seule page Dolibarr Website existe par concept (par exemple </span>`<span class="editor-theme-code">about</span>`<span style="white-space: pre-wrap;">). Le fichier tpl.php est unique. Les slots possèdent leur valeur canonique (FR par défaut) et des surcharges par langue stockées dans </span>`<span class="editor-theme-code">llx_infrasstudio_slot</span>`.

```
<!-- about.tpl.php — UN SEUL fichier pour FR/EN/DE/ES/IT/PT/NL/PL -->
<h1>{{slot:about_title|type=text|default=À propos de nous|label=Titre About}}</h1>
<p>{{slot:about_lead|type=textarea|default=Notre histoire en quelques mots.|label=Accroche}}</p>
```

##### **Récupérer la langue du visiteur dans le gabarit**

Le module résout les slots automatiquement selon la langue détectée. Pour vos propres traitements PHP (afficher la date dans la bonne langue, choisir une image différente par langue), récupérez la langue via :

```
<?php
// helpers fournis par le module
$iso2 = infrasstudio_current_lang();         // 'fr', 'en', 'de', ...
$locale = infrasstudio_current_locale();     // 'fr_FR', 'en_US', 'de_DE', ...
?>
```

##### **Cascade de détection**

<span style="white-space: pre-wrap;">La fonction </span>`<span class="editor-theme-code">infrasstudio_current_lang()</span>`<span style="white-space: pre-wrap;"> détecte la langue dans cet ordre :</span>

1. <span style="white-space: pre-wrap;">Constante </span>`<span class="editor-theme-code">INFRASSTUDIO_LANG_ISO</span>`<span style="white-space: pre-wrap;"> définie par le site (souvent dans </span>`<span class="editor-theme-code">lang.inc.php</span>`).
2. <span style="white-space: pre-wrap;">Paramètre URL </span>`<span class="editor-theme-code">?lang=xx</span>`.
3. Suffixe sur le slug (`<span class="editor-theme-code">about-en.php</span>`<span style="white-space: pre-wrap;"> donne en).</span>
4. Cookie de persistance (`<span class="editor-theme-code">INFRASSTUDIO_LANG_COOKIE</span>`).
5. <span style="white-space: pre-wrap;">Valeur de </span>`<span class="editor-theme-code">$langs->defaultlang</span>`.
6. <span style="white-space: pre-wrap;">En-tête HTTP </span>`<span class="editor-theme-code">Accept-Language</span>`<span style="white-space: pre-wrap;"> du visiteur.</span>

### <span style="color: rgb(35, 111, 161);">Modèle B — Pages sœurs (legacy)</span>

Il s'agit du modèle Dolibarr Website classique : pour chaque page, vous créez un fichier tpl.php par langue.

```
about.php           # FR (canonique)
about-en.php        # EN
about-de.php        # DE
about-es.php        # ES
...
```

Si vous reprenez un site existant qui suit ce modèle, deux options s'offrent à vous :

1. Conserver le modèle avec des stubs du module.
2. Migrer vers le modèle A grâce à l'outil de consolidation en ligne de commande.

### <span style="color: rgb(35, 111, 161);">Conserver le modèle B avec des stubs</span>

<span style="white-space: pre-wrap;">Le module fournit un helper </span>`<span class="editor-theme-code">sister_stub.tpl.php</span>`<span style="white-space: pre-wrap;"> qui réduit chaque page sœur à trois lignes et permet de partager le HTML avec la canonique.</span>

##### **Procédure**

La page canonique reste un tpl.php classique :

```
// page5.tpl.php — canonique FR
<?php // bootstrap dolibarr ... ?>
<html>...<h1>{{slot:about_title|type=text|default=À propos|...}}</h1>...</html>
```

Chaque page sœur devient un stub :

```
<?php
// page42.tpl.php — sister EN
$_infrasstudio_sister_canonical = 'page5.tpl.php';
$_infrasstudio_sister_lang      = 'en';
include dol_buildpath('/infrasstudio/core/tpl/sister_stub.tpl.php', 0);
```

<span style="white-space: pre-wrap;">Le stub force </span>`<span class="editor-theme-code">$_GET['lang'] = 'en'</span>`<span style="white-space: pre-wrap;"> puis délègue le rendu à la canonique. Les surcharges EN sont automatiquement utilisées pour résoudre les slots.</span>

### <span style="color: rgb(35, 111, 161);">Migrer du modèle B vers A en ligne de commande</span>

Un script consolide une famille de pages sœurs en une page canonique et plusieurs stubs :

```
php htdocs/custom/infrasstudio/scripts/consolidate_sister_pages.php <ref-site> \
    [--entity=N] \
    [--base-slug=about] \
    [--dry-run] \
    [--extractor=/path/to/extractor.php]
```

##### **Ce que fait le script**

1. Détecte les groupes de pages sœurs parmi les codes ISO2 pris en charge (en, de, es, it, pt, nl, pl).
2. Pour chaque groupe :
    - Conserve la page tpl FR comme canonique.
    - Extrait les valeurs traduites depuis chaque page sœur (par expression régulière ou via un extracteur personnalisé).
    - <span style="white-space: pre-wrap;">Insère les surcharges dans </span>`<span class="editor-theme-code">llx_infrasstudio_slot</span>`.
    - <span style="white-space: pre-wrap;">Réécrit la canonique avec des slots </span>`<span class="editor-theme-code">{{slot:...}}</span>`.
    - Remplace chaque page sœur par un stub de trois lignes.
3. <span style="white-space: pre-wrap;">Sauvegarde de chaque tpl original avec l'extension </span>`<span class="editor-theme-code">.bak</span>`.

<p class="callout info">**Conseil —**<span style="white-space: pre-wrap;"> Lancez d'abord avec </span>`<span class="editor-theme-code">--dry-run</span>`<span style="white-space: pre-wrap;"> pour visualiser ce que le script va faire sans rien écrire. Lancez en mode réel uniquement après vérification.</span></p>

### <span style="color: rgb(35, 111, 161);">hreflang : déclarer les alternates au navigateur</span>

<span style="white-space: pre-wrap;">Pour que Google sache que vos pages sont des traductions les unes des autres, vous devez émettre des balises </span>`<span class="editor-theme-code"><link rel="alternate" hreflang="..."></span>`<span style="white-space: pre-wrap;"> dans l'en-tête HTML.</span>

Le module fournit un helper qui les génère automatiquement :

```
<head>
    ...
    <?php echo infrasstudio_hreflang_tags($website, $WEBSITE_PAGE); ?>
    ...
</head>
```

Sortie type :

```
<link rel="alternate" hreflang="fr" href="https://exemple.com/about.php" />
<link rel="alternate" hreflang="en" href="https://exemple.com/about-en.php" />
<link rel="alternate" hreflang="de" href="https://exemple.com/about-de.php" />
<link rel="alternate" hreflang="x-default" href="https://exemple.com/about.php" />
```

<p class="callout info">**Compatibilité avec les deux modèles —**<span style="white-space: pre-wrap;"> Pour le modèle A, le helper émet une seule URL canonique avec les langues différenciées par </span>`<span class="editor-theme-code">?lang=</span>`. Pour le modèle B, il émet une URL par page sœur.</p>

### <span style="color: rgb(35, 111, 161);">Sélecteur de langue côté gabarit</span>

<span style="white-space: pre-wrap;">Pour permettre au visiteur de changer de langue, vous devez exposer un sélecteur. Le helper </span>`<span class="editor-theme-code">infrasstudio_translated_url($iso2)</span>`<span style="white-space: pre-wrap;"> génère l'URL équivalente de la page courante dans une autre langue :</span>

```
<nav class="lang-switcher">
    <?php foreach (array('fr', 'en', 'de', 'es') as $iso): ?>
        <a href="<?php echo infrasstudio_translated_url($iso); ?>">
            <?php echo strtoupper($iso); ?>
        </a>
    <?php endforeach; ?>
</nav>
```

### <span style="color: rgb(35, 111, 161);">Charger les fichiers de langue du site</span>

<span style="white-space: pre-wrap;">Si votre site utilise des fichiers </span>`<span class="editor-theme-code">.lang</span>`<span style="white-space: pre-wrap;"> Dolibarr (par exemple pour les libellés de menu), chargez-les en début de tpl :</span>

```
<?php
require_once __DIR__ . '/lang.inc.php';
$langs->loadLangs(array('website_main', 'website_blog'));
?>
```

<span style="white-space: pre-wrap;">Et utilisez les clés via </span>`<span class="editor-theme-code">$langs->trans('Key')</span>`<span style="white-space: pre-wrap;"> ou via le slot avec </span>`<span class="editor-theme-code">default=@lang:Key</span>`.

### <span style="color: rgb(35, 111, 161);">Récapitulatif</span>

**Vous savez désormais :**

- Distinguer le modèle A (slot par langue, recommandé) du modèle B (pages sœurs, legacy).
- <span style="white-space: pre-wrap;">Récupérer la langue du visiteur via </span>`<span class="editor-theme-code">infrasstudio_current_lang()</span>`.
- <span style="white-space: pre-wrap;">Convertir un site existant utilisant le modèle B en utilisant le helper </span>`<span class="editor-theme-code">sister_stub.tpl.php</span>`.
- <span style="white-space: pre-wrap;">Migrer en bloc B vers A grâce à l'outil </span>`<span class="editor-theme-code">consolidate_sister_pages.php</span>`.
- <span style="white-space: pre-wrap;">Émettre les balises hreflang automatiquement avec </span>`<span class="editor-theme-code">infrasstudio_hreflang_tags</span>`.
- <span style="white-space: pre-wrap;">Construire un sélecteur de langue avec </span>`<span class="editor-theme-code">infrasstudio_translated_url</span>`.

</body></html>

# CHAPITRE 22 — Créer ses propres gabarits de page

Lorsque votre client clique sur « + Nouvelle page » dans le Studio, il choisit un gabarit de départ. Ce chapitre vous explique comment créer vos propres gabarits adaptés à la charte de votre site.

### <span style="color: rgb(35, 111, 161);">À quoi sert un gabarit</span>

Un gabarit est un squelette de page qui comporte :

- Du HTML structuré (sections, classes CSS, balises sémantiques).
- Des slots pré-déclarés pour les zones éditables.
- Des valeurs par défaut, pour disposer d'une page complète dès la création.
- Des métadonnées (titre par défaut, slug, type de conteneur).

Lorsqu'un client crée une page depuis un gabarit, le module :

1. <span style="white-space: pre-wrap;">Crée une entrée dans la table </span>`<span class="editor-theme-code">llx_website_page</span>`.
2. <span style="white-space: pre-wrap;">Génère un fichier </span>`<span class="editor-theme-code">page<N>.tpl.php</span>`<span style="white-space: pre-wrap;"> à partir du squelette.</span>
3. <span style="white-space: pre-wrap;">Crée le wrapper Apache </span>`<span class="editor-theme-code"><slug>.php</span>`.
4. Lance un rescan des slots pour les détecter immédiatement.

### <span style="color: rgb(35, 111, 161);">Structure d'un gabarit</span>

<span style="white-space: pre-wrap;">Un gabarit est un dossier dans </span>`<span class="editor-theme-code">htdocs/custom/infrasstudio/templates/</span>`<span style="white-space: pre-wrap;"> :</span>

```
templates/mon-gabarit/
├── meta.php             # Métadonnées du gabarit
└── skeleton.tpl.php     # Le squelette HTML avec slots
```

### <span style="color: rgb(35, 111, 161);">Le fichier meta.php</span>

Il retourne un tableau de configuration :

```
<?php
return array(
    'code'           => 'mon-gabarit',                    // identifiant unique
    'label'          => 'Mon Gabarit',                    // affiché dans l'assistant
    'category'       => 'page',                           // page | landing | blog
    'description'    => "Description courte affichée sous le titre.",
    'icon'           => 'fa-file-lines',                  // icône FontAwesome
    'type_container' => 'page',                           // type Dolibarr Website
    'default_slug'   => 'nouvelle-page',                  // slug suggéré
);
```

<table id="bkmrk-champdescriptioncode" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Champ

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Description

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">code</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Identifiant unique. Doit correspondre au nom du dossier.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">label</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Texte affiché dans la grille de sélection de l'assistant.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">category</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Permet le regroupement visuel (page, landing, blog).

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">icon</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Classe FontAwesome de l'icône de la tuile.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">type_container</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Valeur écrite dans </span>

`<span class="editor-theme-code">llx_website_page.type_container</span>`

<span style="white-space: pre-wrap;">. Valeurs standards : </span>

`<span class="editor-theme-code">page</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">blogpost</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">other</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">menu</span>`

.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">default_slug</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Slug suggéré dans le formulaire. Le client peut le modifier.

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Le fichier skeleton.tpl.php</span>

Il s'agit du squelette HTML, identique à un fichier tpl.php standard, à la différence qu'il contient des marqueurs qui seront remplacés au moment de la création.

##### **Marqueurs disponibles**

<table id="bkmrk-marqueurremplac%C3%A9-par" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Marqueur

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Remplacé par

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">@@PAGEID@@</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">L'identifiant Dolibarr de la nouvelle page (par exemple 42).

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">@@PAGEURL@@</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Le slug URL final (par exemple </span>

`<span class="editor-theme-code">about-keatic</span>`

).

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">@@ISO2@@</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Le code ISO2 de la langue principale (

`<span class="editor-theme-code">fr</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">en</span>`

).

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Exemple complet — gabarit page-libre</span>

##### **meta.php**

```
<?php
return array(
    'code'           => 'page-libre',
    'label'          => 'Page libre',
    'category'       => 'page',
    'description'    => 'Une page simple avec un titre et un grand champ de texte riche.',
    'icon'           => 'fa-file-lines',
    'type_container' => 'page',
    'default_slug'   => 'nouvelle-page',
);
```

##### **skeleton.tpl.php**

```
<?php // BEGIN PHP
$websitekey = basename(__DIR__);
if (! defined('USEDOLIBARRSERVER') && ! defined('USEDOLIBARREDITOR')) {
    require_once __DIR__ . '/master.inc.php';
}
require_once DOL_DOCUMENT_ROOT . '/core/lib/website.lib.php';
require_once DOL_DOCUMENT_ROOT . '/core/website.inc.php';
ob_start();
try {
// END PHP ?>
<html lang="@@ISO2@@">
<head>
    <title>{{slot:page_title|type=text|default=Nouvelle page|label=Titre SEO|group=seo}}</title>
    <meta name="description" content="{{slot:page_meta_description|type=text|default=|label=Meta description|group=seo}}" />
    <link rel="canonical" href="<?php echo $website->virtualhost; ?>/@@PAGEURL@@.php" />
</head>
<body>
    <?php includeContainer('header'); ?>
    <main class="container">
        <h1>{{slot:page_h1|type=text|default=Titre principal|label=H1|group=hero}}</h1>
        <div class="content">
            {{slot:page_body|type=richtext|default=<p>Contenu de la page.</p>|label=Contenu}}
        </div>
    </main>
    <?php includeContainer('footer'); ?>
</body>
</html>
<?php // BEGIN PHP
} catch (Exception $e) { print $e->getMessage(); }
include dol_buildpath('/infrasstudio/core/tpl/website_output.tpl.php', 0);
// END PHP ?>
```

**Le bloc final —**<span style="white-space: pre-wrap;"> N'oubliez pas la ligne </span>`<span class="editor-theme-code">include dol_buildpath('/infrasstudio/core/tpl/website_output.tpl.php', 0);</span>`. C'est elle qui déclenche la résolution des slots et shortcodes au moment du rendu.

### <span style="color: rgb(35, 111, 161);">Localiser vos gabarits hors du module</span>

Si vous souhaitez livrer des gabarits avec votre projet client sans modifier le module, définissez la constante :

```
// htdocs/conf/conf.php ou via dolibarr_set_const
$conf->global->INFRASSTUDIO_TEMPLATE_EXTRA_DIR = '/var/www/monsite/templates';
```

<span style="white-space: pre-wrap;">Le module scanne ce répertoire en complément de </span>`<span class="editor-theme-code">htdocs/custom/infrasstudio/templates/</span>`.

### <span style="color: rgb(35, 111, 161);">Gabarits livrés par défaut</span>

<table id="bkmrk-codedescriptionpage-" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Code

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Description

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">page-free</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Page libre avec titre et un grand champ texte riche. Pour les pages ponctuelles.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">blog-standard</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Article de blog générique avec hero, introduction, corps et appel à l'action.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">example-blog</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Article de blog au design moderne (hero CSS, accroche en italique, image secondaire, articles liés). Adaptable à votre charte.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">example-landing</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Page de destination produit complète (environ 70 slots). Hero, problème, solution, fonctionnalités, contact, FAQ.

</td></tr></tbody></table>

<p class="callout info">**Conseil —**<span style="white-space: pre-wrap;"> Inspirez-vous de </span>`<span class="editor-theme-code">example-landing</span>`<span style="white-space: pre-wrap;"> pour comprendre comment structurer un gabarit complexe avec environ 70 slots organisés en sections.</span></p>

### <span style="color: rgb(35, 111, 161);">Bonnes pratiques pour vos gabarits</span>

- <span style="white-space: pre-wrap;">Préfixez tous les slots du gabarit par un identifiant commun (par exemple </span>`<span class="editor-theme-code">landing_</span>`) pour éviter les collisions entre gabarits.
- <span style="white-space: pre-wrap;">Regroupez les slots avec </span>`<span class="editor-theme-code">group=</span>`<span style="white-space: pre-wrap;"> par section logique (hero, fonctionnalités, contact, etc.).</span>
- Donnez des valeurs par défaut représentatives. Le rédacteur dispose ainsi d'un exemple à modifier plutôt que d'une page vide intimidante.
- Incluez les slots SEO (`<span class="editor-theme-code">page_title</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">page_meta_description</span>`) dans tout gabarit de type page.
- Incluez les balises Open Graph dans l'en-tête HTML pour le partage social.
- Incluez le helper hreflang si le site est multilingue.
- Testez le gabarit en créant une page réelle depuis l'assistant et vérifiez le rendu public.

### <span style="color: rgb(35, 111, 161);">Récapitulatif</span>

**Vous savez désormais :**

- Comprendre l'utilité d'un gabarit (squelette, slots, valeurs par défaut).
- <span style="white-space: pre-wrap;">Créer un dossier </span>`<span class="editor-theme-code">templates//</span>`<span style="white-space: pre-wrap;"> avec </span>`<span class="editor-theme-code">meta.php</span>`<span style="white-space: pre-wrap;"> et </span>`<span class="editor-theme-code">skeleton.tpl.php</span>`.
- Renseigner les métadonnées (code, label, category, icon, type\_container, default\_slug).
- <span style="white-space: pre-wrap;">Utiliser les marqueurs </span>`<span class="editor-theme-code">@@PAGEID@@</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">@@PAGEURL@@</span>`<span style="white-space: pre-wrap;"> et </span>`<span class="editor-theme-code">@@ISO2@@</span>`.
- <span style="white-space: pre-wrap;">Localiser vos gabarits en dehors du module via </span>`<span class="editor-theme-code">INFRASSTUDIO_TEMPLATE_EXTRA_DIR</span>`.
- Suivre les bonnes pratiques (préfixe, regroupement, valeurs par défaut, SEO, multilingue).

Le dernier chapitre de la Partie IV détaille le catalogue produit dynamique en profondeur.

</body></html>

# CHAPITRE 23 — Le catalogue produit dynamique en profondeur

<span style="white-space: pre-wrap;">Le catalogue produit dynamique transforme votre table </span>`<span class="editor-theme-code">llx_product</span>`<span style="white-space: pre-wrap;"> en pages web générées automatiquement. Ce chapitre détaille l'ensemble du fonctionnement côté développeur : architecture, classes, configuration et points d'extension.</span>

### <span style="color: rgb(35, 111, 161);">Architecture en couches</span>

<table id="bkmrk-coucher%C3%B4lestudioprod" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Couche

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Rôle

</th></tr><tr><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">**StudioProductCatalog**

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">Lit les produits Dolibarr (filtres, tris, multilingue) et expose un format normalisé.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">**StudioSolutionWrapper**

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Génère et supprime les wrappers Apache </span>

`<span class="editor-theme-code">solution-<ref>.php</span>`

<span style="white-space: pre-wrap;"> en fonction des produits publiés.</span>

</td></tr><tr><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">**Le gabarit solution-detail (page&lt;X&gt;.tpl.php)**

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">Le gabarit unique qui affiche un produit. Une seule page Dolibarr Website pour N produits.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">**Trigger PRODUCT et CATEGORY**

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">Régénère automatiquement les wrappers à chaque modification de produit ou de catégorie.

</td></tr><tr><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">**Tâche planifiée horaire**

</td><td style="padding: 0.6rem 1rem; border: 1px solid rgb(229, 231, 235);">Filet de sécurité : relance la génération si un trigger a été manqué.

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Le modèle de données produit</span>

Chaque produit Dolibarr utilisé dans le catalogue exploite plusieurs tables :

<table id="bkmrk-tabledonn%C3%A9esllx_prod" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Table

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Données

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">llx_product</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Champs natifs : ref, label, description, prix, tosell.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">llx_product_lang</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Traductions natives (label, description par langue).

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">llx_product_extrafields</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Champs personnalisés canoniques : tagline, hero\_image, badge, cta\_label, cta\_url, deployment, compatibility, support, languages, features (JSON), pricing\_tiers (JSON), infrasstudio\_published.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">llx_infrasstudio_product_translation</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Surcharges par langue des champs personnalisés traduisibles.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">llx_categorie_product</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Liens entre produits et catégories (utilisés pour la cartographie d'univers).

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Provisionner les champs personnalisés</span>

Les onze champs personnalisés nécessaires ne sont pas livrés en standard avec Dolibarr. Pour les créer en une commande, utilisez le script de provisionnement générique :

```
php htdocs/custom/infrasstudio/scripts/preset_default.php \
    htdocs/custom/infrasstudio/presets/keaticweb.json
```

Le fichier JSON livre les définitions par défaut (voir Chapitre 28 pour le format). Vous pouvez créer votre propre preset si vous avez besoin d'autres champs personnalisés.

### <span style="color: rgb(35, 111, 161);">Utiliser StudioProductCatalog</span>

La classe expose plusieurs méthodes pour interroger les produits :

```
dol_include_once('/infrasstudio/class/studioproductcatalog.class.php');
$catalog = new StudioProductCatalog($db);

// Tous les produits publiés, dans la langue courante
$products = $catalog->fetchPublishedProducts(array(), $iso2);

// Filtres
$products = $catalog->fetchPublishedProducts(array(
    'univers' => 'supply-chain',
    'type'    => 'saas',
), $iso2);

// Un produit par référence
$product = $catalog->fetchProductBySlug('supplyflow-pro', $iso2);

// Univers utilisés (pour le filtre du catalogue)
$univers = $catalog->fetchUsedUnivers();
```

##### <span style="color: rgb(22, 145, 121);">Format normalisé d'un produit</span>

```
array(
    'id'           => 5,
    'ref'          => 'supplyflow-pro',
    'label'        => 'SupplyFlow Pro',                    // résolu selon la langue
    'description'  => '<p>Description...</p>',
    'price'        => 290.00,
    'badge'        => 'Nouveau',
    'hero_image'   => '/medias/...',
    'cta_label'    => 'Demander une démo',
    'cta_url'      => '/contact',
    'tagline'      => 'Optimisez votre supply chain...',
    'deployment'   => 'Cloud SaaS',
    'compatibility'=> 'SAP, Oracle, Sage',
    'support'      => '24/7',
    'languages'    => 'fr,en,de',
    'features'     => array('Prévision IA', 'Multi-entrepôts'),
    'pricing_tiers'=> array(...),
    'univers'      => 'supply-chain',
    'type'         => 'saas',
)
```

### <span style="color: rgb(35, 111, 161);">Cartographie catégorie vers univers</span>

Les produits sont rattachés à des catégories Dolibarr. Le module associe chaque catégorie à un univers (concept éditorial : Supply Chain, Health, Legal, etc.).

##### **Cartographie par défaut**

```
// Les six univers livrés par défaut
'supply-chain'        => array(...catégories supply chain),
'health'              => array(...catégories santé),
'legal'               => array(...catégories juridique),
'digital-humanities'  => array(...catégories sciences humaines),
'transversal'         => array(...catégories outils transversaux),
'fsm'                 => array(...catégories field service)
```

##### **Surcharge par JSON**

Pour personnaliser, définissez la constante :

```
// Via dolibarr_set_const ou via la page de configuration admin
$conf->global->INFRASSTUDIO_PRODUCT_UNIVERS_MAP = json_encode(array(
    'mon-univers' => array(12, 13, 14),  // identifiants de catégories
    'autre'       => array(15, 16),
));
```

### <span style="color: rgb(35, 111, 161);">StudioSolutionWrapper</span>

Cette classe gère la génération des wrappers Apache à partir des produits publiés.

##### **Génération manuelle**

```
dol_include_once('/infrasstudio/class/studiosolutionwrapper.class.php');
require_once DOL_DOCUMENT_ROOT . '/website/class/website.class.php';

$website = new Website($db);
$website->fetch(0, 'monsite');

$wrapper = new StudioSolutionWrapper($db);
$stats = $wrapper->rebuildAll($website, '/var/www/monsite');
print_r($stats);
// array('created' => 3, 'updated' => 2, 'deleted' => 1, 'skipped' => 5)
```

##### **Anatomie d'un wrapper généré**

```
<?php
// /var/www/monsite/solution-supplyflow-pro.php
// Generated by StudioSolutionWrapper — do not edit manually.
$solution_ref = 'supplyflow-pro';
$infrasstudio_current_product_ref = 'supplyflow-pro';
global $dolibarr_main_data_root, $conf;
if (empty($dolibarr_main_data_root)) {
    $res = include './page42.tpl.php';   // page solution-detail
} else {
    $res = include $dolibarr_main_data_root
        . ($conf->entity > 1 ? '/' . $conf->entity : '')
        . '/website/monsite/page42.tpl.php';
}
if ($res === false) { http_response_code(500); print 'Failed to make include'; }
```

<p class="callout success">**Sécurité anti-collision —**<span style="white-space: pre-wrap;"> Le module ne touche qu'aux wrappers qu'il a lui-même créés (présence du marqueur « StudioSolutionWrapper » dans l'en-tête du fichier). Les pages Dolibarr standards portant un slug commençant par </span>`<span class="editor-theme-code">solution-</span>`<span style="white-space: pre-wrap;"> sont préservées.</span></p>

### <span style="color: rgb(35, 111, 161);">Configuration du générateur de wrappers</span>

<table id="bkmrk-constanter%C3%B4leinfrass" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Constante

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Rôle

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">INFRASSTUDIO_WEBSITE_KEY</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Référence du site cible.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">INFRASSTUDIO_PUBLIC_DOCROOT</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Docroot Apache absolu (par exemple </span>

`<span class="editor-theme-code">/var/www/monsite</span>`

).

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">INFRASSTUDIO_SITE_<id>_WRAPPER_PREFIX</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Préfixe des wrappers (par défaut </span>

`<span class="editor-theme-code">solution-</span>`

<span style="white-space: pre-wrap;">). Exemples : </span>

`<span class="editor-theme-code">produit-</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">service-</span>`

.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">INFRASSTUDIO_SITE_<id>_WRAPPER_TEMPLATE_PAGEURL</span>`

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Slug du gabarit solution-detail (par défaut </span>

`<span class="editor-theme-code">solution-detail</span>`

).

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Le gabarit solution-detail</span>

<span style="white-space: pre-wrap;">Il s'agit d'une page Dolibarr Website classique (avec son slug et son tpl.php), mais utilisée par tous les wrappers. Elle reçoit la variable globale </span>`<span class="editor-theme-code">$solution_ref</span>`<span style="white-space: pre-wrap;"> qui identifie le produit à afficher.</span>

##### **Squelette type**

```
<?php
// page42.tpl.php (slug='solution-detail', type_container='page')
require_once __DIR__ . '/master.inc.php';
require_once DOL_DOCUMENT_ROOT . '/core/lib/website.lib.php';
require_once DOL_DOCUMENT_ROOT . '/core/website.inc.php';

dol_include_once('/infrasstudio/class/studioproductcatalog.class.php');
$catalog = new StudioProductCatalog($db);
$iso2 = infrasstudio_current_lang();
$product = $catalog->fetchProductBySlug($solution_ref, $iso2);
if (!$product) {
    http_response_code(404);
    print '<h1>Produit introuvable</h1>';
    exit;
}

ob_start();
try {
?>
<html lang="<?php echo $iso2; ?>">
<head>
    <title><?php echo dol_escape_htmltag($product['label']); ?></title>
</head>
<body>
    <section class="hero">
        <h1><?php echo dol_escape_htmltag($product['label']); ?></h1>
        <p><?php echo dol_escape_htmltag($product['tagline']); ?></p>
        <img src="<?php echo $product['hero_image']; ?>" alt="...">
    </section>
    <section class="features">
        <ul>
        <?php foreach ($product['features'] as $feature): ?>
            <li><?php echo dol_escape_htmltag($feature); ?></li>
        <?php endforeach; ?>
        </ul>
    </section>
</body>
</html>
<?php
} catch (Exception $e) { print $e->getMessage(); }
include dol_buildpath('/infrasstudio/core/tpl/website_output.tpl.php', 0);
```

**Mélanger slots et données produit —**<span style="white-space: pre-wrap;"> Vous pouvez combiner les deux : les zones éditoriales (par exemple un titre marketing au-dessus de la grille) en slots, et les zones produit (label, prix, fonctionnalités) lues via </span>`<span class="editor-theme-code">StudioProductCatalog</span>`. Les deux cohabitent sans conflit.

### <span style="color: rgb(35, 111, 161);">Le trigger PRODUCT et CATEGORY</span>

Le module installe un trigger qui écoute :

- `<span class="editor-theme-code">PRODUCT_CREATE</span>`
- `<span class="editor-theme-code">PRODUCT_MODIFY</span>`
- `<span class="editor-theme-code">PRODUCT_DELETE</span>`
- `<span class="editor-theme-code">PRODUCT_PRICE_MODIFY</span>`
- `<span class="editor-theme-code">CATEGORY_LINK</span>`<span style="white-space: pre-wrap;"> (uniquement si l'objet lié est un produit)</span>
- `<span class="editor-theme-code">CATEGORY_UNLINK</span>`

<span style="white-space: pre-wrap;">À chaque événement, le trigger appelle </span>`<span class="editor-theme-code">StudioSolutionWrapper::rebuildAll()</span>`<span style="white-space: pre-wrap;"> sur le site configuré.</span>

<p class="callout info">**Note —**<span style="white-space: pre-wrap;"> Si </span>`<span class="editor-theme-code">INFRASSTUDIO_WEBSITE_KEY</span>`<span style="white-space: pre-wrap;"> ou </span>`<span class="editor-theme-code">INFRASSTUDIO_PUBLIC_DOCROOT</span>`<span style="white-space: pre-wrap;"> ne sont pas configurées, le trigger se termine silencieusement. Ni bruit, ni erreur. Cette discrétion convient aux instances Dolibarr qui n'utilisent pas le catalogue dynamique.</span></p>

### <span style="color: rgb(35, 111, 161);">La tâche planifiée horaire (filet de sécurité)</span>

<span style="white-space: pre-wrap;">Une tâche planifiée s'exécute toutes les heures et appelle </span>`<span class="editor-theme-code">StudioSolutionWrapper::rebuildAllConfigured()</span>`. Elle lit les constantes et relance la régénération.

Cette tâche apporte les bénéfices suivants :

- Rattrapage si un trigger a été manqué (import en masse, modification SQL directe, etc.).
- Synchronisation après une migration de serveur.
- Garantie de cohérence sans intervention manuelle.

### <span style="color: rgb(35, 111, 161);">Reconstruction manuelle en ligne de commande</span>

```
php htdocs/custom/infrasstudio/scripts/rebuild_solution_wrappers.php \
    <ref-site-ou-id> <docroot-public> [entity]

# Exemple
php htdocs/custom/infrasstudio/scripts/rebuild_solution_wrappers.php \
    monsite /var/www/monsite 2
```

### <span style="color: rgb(35, 111, 161);">Aides visuelles dans le Studio</span>

Deux indicateurs visuels accompagnent l'administrateur dans la prise en main et la maintenance d'une instance qui utilise le catalogue. Ils sont là pour signaler immédiatement les problèmes de configuration et les actions ponctuelles qui n'ont de sens qu'à un moment précis du cycle de vie d'un site.

##### **Bandeau « Produits de démonstration » dans l'éditeur Produits**

<span style="white-space: pre-wrap;">Quand un site a été créé depuis un template préfabriqué (Vibrant ou Editorial), le seed pose six produits factices catégorisés pour que le catalogue soit immédiatement peuplé et visualisable. Ces produits ont vocation à être remplacés par les vrais produits du client. L'éditeur Produits du Studio détecte automatiquement leur présence — via le préfixe de référence </span>`<span class="editor-theme-code">demo-*</span>`<span style="white-space: pre-wrap;"> posé par le seed — et affiche un bandeau jaune en haut de la grille avec deux actions en un clic :</span>

- **Dépublier en masse**<span style="white-space: pre-wrap;"> — bascule </span>`<span class="editor-theme-code">infrasstudio_published=0</span>`<span style="white-space: pre-wrap;"> sur les six produits démo. Ils restent dans Dolibarr (cohérents avec une éventuelle migration ultérieure) mais disparaissent du catalogue public et de l'index du site. Réversible en un clic.</span>
- **Supprimer en masse**<span style="white-space: pre-wrap;"> — efface complètement les six produits, leurs traductions </span>`<span class="editor-theme-code">llx_product_lang</span>`<span style="white-space: pre-wrap;">, leurs extrafields </span>`<span class="editor-theme-code">llx_product_extrafields</span>`<span style="white-space: pre-wrap;"> et leurs liaisons à la catégorie démo. Irréversible. Une modale de confirmation Studio garde le doigt sur le bouton.</span>

<span style="white-space: pre-wrap;">Le bandeau disparaît automatiquement dès qu'aucun produit démo n'est détecté dans l'entité courante. Aucun risque d'effacer des produits réels : la détection se base strictement sur le préfixe </span>`<span class="editor-theme-code">demo-</span>`<span style="white-space: pre-wrap;"> et sur la liaison à la catégorie démo créée par le seed.</span>

##### **Badge d'alerte dans la barre du Studio**

La barre supérieure du Studio (visible sur toutes les pages de l'éditeur) intègre un badge d'alerte qui clignote en rouge lorsque la configuration du catalogue présente un problème bloquant. Le badge agrège plusieurs vérifications croisées et synthétise leur état en un seul point d'attention :

- **Module InfraSStudio désactivé**<span style="white-space: pre-wrap;"> sur l'entité courante (cas typique d'une migration multi-entité partiellement appliquée).</span>
- **Tables InfraSStudio manquantes**<span style="white-space: pre-wrap;"> — la classe </span>`<span class="editor-theme-code">StudioProductCatalog</span>`<span style="white-space: pre-wrap;"> a besoin de </span>`<span class="editor-theme-code">llx_infrasstudio_slot</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">llx_infrasstudio_media</span>`<span style="white-space: pre-wrap;"> et </span>`<span class="editor-theme-code">llx_infrasstudio_product_translation</span>`<span style="white-space: pre-wrap;"> ; le badge s'allume si l'une d'elles est absente (échec de migration, restauration partielle).</span>
- **Docroot Apache introuvable**<span style="white-space: pre-wrap;"> — la constante </span>`<span class="editor-theme-code">INFRASSTUDIO_PUBLIC_DOCROOT</span>`<span style="white-space: pre-wrap;"> pointe vers un chemin qui n'existe pas physiquement, ce qui empêche les wrappers </span>`<span class="editor-theme-code">solution-*.php</span>`<span style="white-space: pre-wrap;"> d'être écrits.</span>
- **Référence de site cassée**<span style="white-space: pre-wrap;"> — la constante </span>`<span class="editor-theme-code">INFRASSTUDIO_WEBSITE_KEY</span>`<span style="white-space: pre-wrap;"> renvoie vers un site supprimé ou inexistant.</span>
- **Champs personnalisés produit manquants**<span style="white-space: pre-wrap;"> — un ou plusieurs des onze extrafields utilisés par </span>`<span class="editor-theme-code">StudioProductCatalog</span>`<span style="white-space: pre-wrap;"> n'existent pas dans </span>`<span class="editor-theme-code">llx_extrafields</span>`, ce qui dégraderait le rendu des fiches produit.

<span style="white-space: pre-wrap;">Au survol, le badge déplie une mini liste détaillée des incidents avec un lien direct vers la page Diagnostic complète, qui les résout un par un. Cette approche évite que l'administrateur découvre un dysfonctionnement par un client qui voit une page blanche, en remontant le problème </span>**avant**<span style="white-space: pre-wrap;"> que les visiteurs ne soient impactés.</span>

### <span style="color: rgb(35, 111, 161);">Récapitulatif</span>

**Vous savez désormais :**

- Comprendre l'architecture du catalogue (StudioProductCatalog, StudioSolutionWrapper, gabarit, trigger, tâche planifiée).
- Provisionner les champs personnalisés produit avec le preset générique.
- <span style="white-space: pre-wrap;">Interroger les produits via </span>`<span class="editor-theme-code">StudioProductCatalog</span>`.
- <span style="white-space: pre-wrap;">Cartographier les catégories Dolibarr vers vos univers via </span>`<span class="editor-theme-code">INFRASSTUDIO_PRODUCT_UNIVERS_MAP</span>`.
- Personnaliser la cartographie des types de produit et le préfixe d'URL des fiches via les constantes catalogue.
- <span style="white-space: pre-wrap;">Activer ou désactiver le filtre </span>`<span class="editor-theme-code">infrasstudio_published</span>`<span style="white-space: pre-wrap;"> selon que votre site utilise ou non la notion de brouillon catalogue.</span>
- <span style="white-space: pre-wrap;">Comprendre comment </span>`<span class="editor-theme-code">StudioSolutionWrapper::rebuildAll()</span>`<span style="white-space: pre-wrap;"> génère les wrappers Apache.</span>
- Configurer le préfixe et le slug du gabarit par site.
- <span style="white-space: pre-wrap;">Écrire le gabarit </span>`<span class="editor-theme-code">solution-detail</span>`<span style="white-space: pre-wrap;"> qui sert tous les produits.</span>
- Comprendre le rôle du trigger automatique et de la tâche planifiée de sécurité.
- Lancer une reconstruction manuelle en ligne de commande.
- Utiliser le bandeau de gestion des produits de démonstration livrés avec les templates Vibrant et Editorial.
- Identifier les incidents de configuration du catalogue grâce au badge d'alerte de la barre du Studio.

**Fin de la Partie IV —**<span style="white-space: pre-wrap;"> Vous maîtrisez désormais l'intégration côté développeur : préparer un site, annoter avec des slots, comprendre la grammaire, brancher des données Dolibarr, gérer le multilingue, créer vos gabarits et exploiter le catalogue dynamique. Vous êtes en mesure de livrer un site clé en main.</span>

La Partie V aborde l'administration et la maintenance. Si vous êtes administrateur Dolibarr, c'est votre prochaine destination.

**Fin de la Partie IV —**<span style="white-space: pre-wrap;"> Vous maîtrisez désormais l'intégration côté développeur : préparer un site, annoter avec des slots, comprendre la grammaire, brancher des données Dolibarr, gérer le multilingue, créer vos gabarits et exploiter le catalogue dynamique. Vous êtes en mesure de livrer un site clé en main.</span>

La Partie V aborde l'administration et la maintenance. Si vous êtes administrateur Dolibarr, c'est votre prochaine destination.

</body></html>

# CHAPITRE 24 — Les formulaires publics

InfraSStudio embarque un moteur de formulaires publics conçu pour transformer la moindre saisie web en lead qualifié dans Dolibarr. Un formulaire de contact rempli sur un site géré par le module ne déclenche pas un simple envoi d'email : il alimente automatiquement le CRM, ouvre un ticket, prévient les équipes commerciales et déclenche, au besoin, un rappel en agenda. Ce chapitre détaille la mécanique interne, la configuration côté administrateur et l'intégration dans un site Dolibarr Website.

### <span style="color: rgb(35, 111, 161);">Architecture du moteur</span>

L'architecture repose sur trois pièces : un descripteur JSON par formulaire, un point d'entrée unique côté serveur, et une chaîne d'adapters exécutés à chaque soumission. Aucun code PHP n'est nécessaire pour ajouter ou modifier un formulaire : il suffit d'éditer le descripteur depuis l'interface d'administration ou directement depuis l'éditeur Studio.

<table id="bkmrk-pi%C3%A8cer%C3%B4leendpoint-un" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Pièce

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Rôle

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Endpoint unique**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">public/forms/submit.php</span>`<span style="white-space: pre-wrap;"> reçoit toutes les soumissions. Le formulaire est identifié par son nom inséré en champ caché </span>`<span class="editor-theme-code">form_name</span>`.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Descripteur JSON**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Une ligne dans </span>`<span class="editor-theme-code">llx_infrasstudio_form_config</span>`<span style="white-space: pre-wrap;"> par formulaire. Décrit les champs, les règles de validation, les paramètres anti-spam et les adapters à exécuter.</span>

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**Pipeline d'adapters**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Six étapes activables à la carte : validation, anti-spam, tiers, contact, ticket, notification, agenda.

</td></tr></tbody></table>

##### **Le pipeline étape par étape**

Chaque soumission acceptée traverse la chaîne ci-dessous. Chaque étape s'active indépendamment dans le descripteur, ce qui permet de couvrir aussi bien un formulaire de newsletter minimaliste qu'une demande de démonstration commerciale complète.

<table id="bkmrk-adaptereffet-sur-la-" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.95em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Adapter

</th><th class="align-left" style="padding: 0.6rem 1rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Effet sur la soumission

</th></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**antispam**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Honeypot, délai minimum de remplissage, rate-limit par adresse IP, captcha délégué au gestionnaire Dolibarr actif.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**tiers**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Recherche ou création d'une société dans </span>`<span class="editor-theme-code">llx_societe</span>`. Application d'une catégorie et d'une origine.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**contact**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Recherche ou création d'un contact dans </span>`<span class="editor-theme-code">llx_socpeople</span>`, libre ou rattaché au tiers.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**ticket**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Ouverture d'un ticket Dolibarr avec sujet, message, catégorie et sévérité.

</td></tr><tr><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**notification**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Envoi d'un email interne à l'équipe commerciale et d'un accusé de réception au visiteur.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">**agenda**

</td><td style="padding: 0.5rem 1rem; border: 1px solid rgb(229, 231, 235);">Création d'un événement de rappel lié au tiers et au ticket.

</td></tr></tbody></table>

### <span style="color: rgb(35, 111, 161);">Configurer un formulaire</span>

<span style="white-space: pre-wrap;">Deux interfaces complémentaires sont disponibles. </span>**L'administration avancée**<span style="white-space: pre-wrap;"> se trouve dans </span>**Outils → InfraS → Formulaires**<span style="white-space: pre-wrap;"> : grille des configurations, statistiques de soumission, accès au descripteur JSON brut. </span>**L'éditeur Studio**<span style="white-space: pre-wrap;"> propose désormais un onglet </span>**Formulaires**<span style="white-space: pre-wrap;"> avec un inspector inline qui couvre la majorité des réglages courants sans repasser par l'administration Dolibarr.</span>

##### **Créer un nouveau formulaire**

<span style="white-space: pre-wrap;">Le bouton </span>**« + Nouveau formulaire »**<span style="white-space: pre-wrap;"> de l'onglet Formulaires de l'éditeur Studio ouvre une modale en quatre champs :</span>

- <span style="white-space: pre-wrap;">le </span>**libellé affiché en administration**<span style="white-space: pre-wrap;"> (facultatif) ;</span>
- l'**identifiant technique**<span style="white-space: pre-wrap;"> (a-z, 0-9, tiret, underscore — utilisé dans le HTML, unique par entité) ;</span>
- <span style="white-space: pre-wrap;">le </span>**type**<span style="white-space: pre-wrap;"> (</span>**contact**<span style="white-space: pre-wrap;">, </span>**newsletter**<span style="white-space: pre-wrap;">, </span>**demo**<span style="white-space: pre-wrap;"> ou </span>**generic**) — le type définit les champs par défaut et le pipeline par défaut ;
- <span style="white-space: pre-wrap;">un </span>**modèle de design**<span style="white-space: pre-wrap;"> (facultatif) — voir la section </span>**Les starter design templates**<span style="white-space: pre-wrap;"> ci-dessous.</span>

Le formulaire fraîchement créé est immédiatement sélectionné dans l'inspector et prêt à recevoir d'éventuels ajustements (champs, anti-spam, design, pipeline). L'identifiant technique sert d'ancrage tout au long du cycle de vie : il est référencé dans le HTML, dans le viewer de soumissions et dans les journaux.

##### **Gérer les champs depuis l'éditeur**

<span style="white-space: pre-wrap;">Dans l'onglet </span>**Formulaires**<span style="white-space: pre-wrap;"> de l'éditeur Studio, la section </span>**Champs**<span style="white-space: pre-wrap;"> permet d'</span>**ajouter**<span style="white-space: pre-wrap;">, de </span>**réordonner**<span style="white-space: pre-wrap;"> (boutons monter / descendre) et de </span>**supprimer**<span style="white-space: pre-wrap;"> un champ sans toucher au JSON. L'ordre défini ici est exactement l'ordre d'affichage du formulaire public. Chaque champ porte un interrupteur </span>**Obligatoire**<span style="white-space: pre-wrap;"> : lorsqu'il est activé, un astérisque </span>`<span class="editor-theme-code">*</span>`<span style="white-space: pre-wrap;"> est ajouté automatiquement à côté du libellé sur le formulaire rendu. Les saisies en cours (libellé, type, placeholder) sont préservées lors d'un déplacement, d'un ajout ou d'une suppression.</span>

##### **Supprimer un formulaire**

<span style="white-space: pre-wrap;">La section </span>**« Zone dangereuse »**<span style="white-space: pre-wrap;"> en bas de l'inspector expose un bouton </span>**Supprimer ce formulaire**<span style="white-space: pre-wrap;">. La suppression efface uniquement la configuration : les soumissions déjà enregistrées dans </span>`<span class="editor-theme-code">llx_infrasstudio_form_submission</span>`<span style="white-space: pre-wrap;"> sont conservées (traçabilité RGPD préservée). Une modale de confirmation Studio garde le doigt sur le bouton — la fenêtre </span>`<span class="editor-theme-code">confirm()</span>`<span style="white-space: pre-wrap;"> native du navigateur n'est jamais utilisée. Le même contrôle est disponible depuis </span>**Outils → InfraS → Formulaires**<span style="white-space: pre-wrap;"> via le bouton </span>**Supprimer**<span style="white-space: pre-wrap;"> de chaque ligne.</span>

##### **Le descripteur JSON**

Le cœur de la configuration est un descripteur JSON qui décrit le formulaire sous une forme structurée. L'éditeur d'administration valide la syntaxe à l'enregistrement et propose une référence dépliable de toutes les clés supportées pour éviter d'avoir à mémoriser la grammaire.

```
{
    "antispam": { "honeypot": true, "min_fill_seconds": 3, "rate_limit_per_hour": 5, "captcha": true },
    "consent":  { "required": true, "field_name": "consent", "text": "..." },
    "fields":   {
        "name":    { "required": true, "type": "text",  "maxlength": 100 },
        "email":   { "required": true, "type": "email", "maxlength": 200 },
        "message": { "required": true, "type": "text",  "maxlength": 5000 }
    },
    "tiers":        { "enabled": true,  "lookup_by_email": true, "category_label": "Lead web" },
    "ticket":       { "enabled": true,  "category_code":   "COMMERCIAL" },
    "notification": { "autoreply_enabled": true, "autoreply_template_label": "Accusé de réception" },
    "template_override": "site:contact.tpl.php"
}
```

<span style="white-space: pre-wrap;">La clé </span>`<span class="editor-theme-code">template_override</span>`<span style="white-space: pre-wrap;"> est facultative — sans elle, le moteur utilise le template par défaut du type. Voir la section </span>**Intégrer le formulaire dans un site**<span style="white-space: pre-wrap;"> pour les trois modes de résolution.</span>

##### **Tester un formulaire avant mise en ligne**

La fiche admin de chaque formulaire (**Outils → InfraS → Formulaires**<span style="white-space: pre-wrap;"> → ouvrir un formulaire) expose un bouton </span>**« Tester ce formulaire »**<span style="white-space: pre-wrap;"> qui simule une soumission de bout en bout sans passer par le site public. Le tester forge un payload factice à partir des champs déclarés dans la configuration, traverse le pipeline complet (tiers, contact, ticket, notification, agenda) et restitue un rapport détaillé étape par étape.</span>

Les entités créées en mode test (Société, Contact, Ticket, événement d'agenda) sont :

- **marquées explicitement**<span style="white-space: pre-wrap;"> : leur libellé est préfixé </span>`<span class="editor-theme-code">[TEST]</span>`<span style="white-space: pre-wrap;"> pour être reconnaissables au premier coup d'œil dans Dolibarr ;</span>
- **flaguées en base**<span style="white-space: pre-wrap;"> : la soumission correspondante porte </span>`<span class="editor-theme-code">is_test=1</span>`<span style="white-space: pre-wrap;"> dans </span>`<span class="editor-theme-code">llx_infrasstudio_form_submission</span>`<span style="white-space: pre-wrap;"> ;</span>
- **purgeables en un clic**<span style="white-space: pre-wrap;"> : le bouton </span>**Purger les données de test**<span style="white-space: pre-wrap;"> supprime en cascade tous les enregistrements de test (événement → ticket → contact → société → soumission), avec un filet de sécurité qui empêche d'effacer une société qui aurait reçu des soumissions de production entre-temps.</span>

<span style="white-space: pre-wrap;">En mode test, le captcha est </span>**volontairement bypassé**<span style="white-space: pre-wrap;"> par le moteur — l'administrateur est déjà authentifié dans Dolibarr, exiger un code image en plus n'aurait pas de sens. Les autres contrôles antispam (honeypot, délai minimum de remplissage, rate-limit) restent actifs et sont exercés avec des valeurs forgées correctement par le tester, ce qui permet de valider la chaîne complète.</span>

<span style="white-space: pre-wrap;">L'usage typique : après chaque modification importante d'un formulaire (ajout d'un champ, changement de catégorie ticket, nouveau template d'accusé), cliquer une fois sur </span>**Tester ce formulaire**, vérifier dans le rapport que chaque adapter s'est exécuté avec succès, puis purger. Cinq secondes de validation qui évitent de découvrir un bug en production via un vrai client.

### <span style="color: rgb(35, 111, 161);">Connecter le formulaire à votre CRM</span>

L'intérêt principal du moteur réside dans la chaîne de traitement qu'il déclenche au moment de la soumission. Chaque adapter peut être activé indépendamment selon les besoins.

##### **Tiers et contact**

<span style="white-space: pre-wrap;">Lorsque l'adapter tiers est actif, le moteur recherche d'abord une société existante dont l'adresse email correspond à celle saisie ; à défaut, il regarde si l'email appartient à un contact rattaché à une société, puis tente une correspondance par nom d'entreprise. Si aucune correspondance n'est trouvée, un nouveau tiers est créé, catégorisé automatiquement et associé à un canal d'origine (extrafield </span>`<span class="editor-theme-code">origine</span>`<span style="white-space: pre-wrap;"> renseigné depuis le dictionnaire </span>`<span class="editor-theme-code">c_input_reason</span>`). La même logique existe pour les contacts, utile notamment pour les inscriptions à la newsletter qui ne nécessitent pas la création d'une société.

##### **Ouverture d'un ticket**

L'adapter ticket ouvre un ticket Dolibarr rattaché au tiers résolu. Le sujet et le message sont construits soit à partir des champs du formulaire, soit à partir de gabarits permettant d'injecter dynamiquement le nom du visiteur, sa demande, l'adresse IP d'origine ou tout autre élément du contexte. Catégorie et sévérité sont déterminées par les codes du dictionnaire Dolibarr (`<span class="editor-theme-code">llx_c_ticket_category</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">llx_c_ticket_severity</span>`).

##### **Notification et accusé de réception**

<span style="white-space: pre-wrap;">Deux emails partent automatiquement à chaque soumission acceptée : une </span>**notification interne**<span style="white-space: pre-wrap;"> adressée à l'équipe pour traiter la demande, et un </span>**accusé de réception**<span style="white-space: pre-wrap;"> destiné au visiteur pour le rassurer. Les deux sont indépendants — il est possible d'envoyer uniquement la notification interne, uniquement l'accusé de réception, ou les deux. Tous les paramètres sont accessibles depuis l'éditeur Studio, onglet </span>**Pipeline**<span style="white-space: pre-wrap;">, section </span>**Notifications email**, sans avoir à manipuler le JSON brut.

###### **Les champs disponibles dans le wizard**

Chaque champ porte une tooltip d'aide affichée en gris sous l'input. Le tableau ci-dessous récapitule leur rôle.

<table id="bkmrk-champeffetemail-dest" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.93em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Champ

</th><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Effet

</th></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Email destinataire admin**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Adresse(s) qui reçoivent l'alerte interne. Plusieurs destinataires séparés par une virgule. Laisser vide pour désactiver la notification interne.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Modèle du sujet admin**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Objet du mail interne. Accepte les variables </span>

`<span class="editor-theme-code">{{payload.X}}</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">{{form_name}}</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">{{submission_id}}</span>`

.

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Corps de la notification admin**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Corps du mail interne. Laisser vide pour générer automatiquement un récapitulatif de tous les champs saisis. Permet de mettre en forme une notification riche (tableau, branding, lien vers la fiche soumission).

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Le corps admin est du HTML**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Interrupteur (toggle). Si activé, le corps est interprété comme du HTML ; sinon il part en texte brut et les balises apparaissent telles quelles.

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Champ payload utilisé comme Reply-To**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Nom du champ contenant l'email du visiteur (défaut : </span>

`<span class="editor-theme-code">email</span>`

<span style="white-space: pre-wrap;">). Un clic sur </span>

**Répondre**

<span style="white-space: pre-wrap;"> dans la messagerie répondra directement au visiteur, pas à l'expéditeur technique.</span>

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Activer l'accusé de réception**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Interrupteur. Si activé, le visiteur reçoit un mail de confirmation à l'adresse qu'il a saisie.

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Champ payload de l'adresse visiteur**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Nom du champ du formulaire contenant l'adresse du visiteur. Par défaut </span>

`<span class="editor-theme-code">email</span>`

.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Sujet de l'accusé de réception**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Objet du mail reçu par le visiteur. </span>

**Ignoré**

<span style="white-space: pre-wrap;"> si un modèle est sélectionné ci-dessous.</span>

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Corps de l'accusé de réception**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Corps du mail reçu par le visiteur. </span>

**Ignoré**

<span style="white-space: pre-wrap;"> si un modèle est sélectionné. Laisser vide pour un texte générique de remerciement.</span>

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Le corps de l'accusé est du HTML**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Interrupteur (toggle) équivalent côté visiteur.

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Modèle d'accusé de réception**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Liste déroulante des modèles d'email Dolibarr de type </span>

`<span class="editor-theme-code">infrasstudio_form</span>`

<span style="white-space: pre-wrap;">. Quand un modèle est sélectionné, il prend la main sur les champs </span>

**Sujet**

<span style="white-space: pre-wrap;"> et </span>

**Corps**

<span style="white-space: pre-wrap;"> ci-dessus. Avantage : le texte est centralisé dans </span>

**Configuration → Emails → Modèles d'e-mails**

, partagé entre tous les formulaires qui pointent dessus.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Adresse expéditeur (From) / Nom expéditeur (From)**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Surcharge per-formulaire de l'adresse et du nom apparaissant comme expéditeur des deux mails. Vides : utilise </span>

`<span class="editor-theme-code">MAIN_MAIL_EMAIL_FROM</span>`

<span style="white-space: pre-wrap;"> et le nom de la société configurée dans Dolibarr.</span>

</td></tr></tbody></table>

###### **Variables disponibles dans les templates**

Les sujets et corps de mail (admin et accusé) acceptent une substitution simple. Aucune logique conditionnelle : les marqueurs inconnus sont laissés en clair, ce qui facilite le debug.

<table id="bkmrk-variablevaleur%7B%7Bpayl" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.93em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Variable

</th><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Valeur

</th></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">{{payload.X}}</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Valeur du champ </span>

`<span class="editor-theme-code">X</span>`

<span style="white-space: pre-wrap;"> saisi par le visiteur. Raccourci : </span>

`<span class="editor-theme-code">{{X}}</span>`

.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">{{form_name}}</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Identifiant technique du formulaire actif.

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">{{submission_id}}</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Numéro de la soumission, utile pour bâtir un lien admin direct.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">{{ip}}</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">IP du visiteur.

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">{{mysoc.name}}</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">{{mysoc.email}}</span>`

<span style="white-space: pre-wrap;">, </span>

`<span class="editor-theme-code">{{mysoc.phone}}</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Coordonnées de la société configurée dans Dolibarr.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">{{config.X}}</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Clé de premier niveau du JSON config courant.

</td></tr></tbody></table>

###### **Exemple — notification interne mise en forme**

Sujet :

```
[{{form_name}}] Nouvelle demande de {{payload.name}} ({{payload.company}})
```

<span style="white-space: pre-wrap;">Corps HTML (interrupteur </span>**Le corps admin est du HTML**<span style="white-space: pre-wrap;"> activé) :</span>

```
<div style="font-family:Arial,sans-serif;max-width:600px;color:#333">
  <div style="background:#0f172a;color:#fff;padding:16px 20px;border-radius:6px 6px 0 0">
    <h2 style="margin:0;font-size:18px">Nouvelle demande de contact</h2>
    <div style="font-size:12px;opacity:.8;margin-top:4px">
      Formulaire : {{form_name}} · Soumission #{{submission_id}}
    </div>
  </div>
  <div style="border:1px solid #e2e8f0;border-top:0;padding:20px;border-radius:0 0 6px 6px">
    <table style="width:100%;border-collapse:collapse;font-size:14px">
      <tr><td style="color:#64748b;width:140px">Nom</td><td><strong>{{payload.name}}</strong></td></tr>
      <tr><td style="color:#64748b">Société</td><td>{{payload.company}}</td></tr>
      <tr><td style="color:#64748b">Email</td><td><a href="mailto:{{payload.email}}">{{payload.email}}</a></td></tr>
    </table>
    <p style="color:#64748b;font-size:13px;margin:20px 0 6px">Message</p>
    <div style="background:#f8fafc;border-left:3px solid #6366f1;padding:12px 14px;white-space:pre-wrap">{{payload.message}}</div>
    <div style="margin-top:24px;padding-top:14px;border-top:1px solid #e2e8f0;font-size:12px;color:#94a3b8">
      IP : {{ip}} · Reçu via {{mysoc.name}}
    </div>
  </div>
</div>
```

Côté boîte mail, l'équipe reçoit un message présenté en tableau avec une bande de couleur, le nom et l'email cliquables, le contenu du message dans un encadré, et un pied technique discret avec l'IP.

##### **Cohabitation avec le module Gestionnaire de tickets**

<span style="white-space: pre-wrap;">Quand l'adapter ticket d'InfraSStudio crée un ticket Dolibarr à la suite d'une soumission, le module Gestionnaire de tickets enverrait normalement son propre mail natif </span>`<span class="editor-theme-code">TICKET_CREATE</span>`<span style="white-space: pre-wrap;"> au tiers et sa propre alerte interne. Pour éviter les doublons, InfraSStudio positionne deux drapeaux dans le contexte de création :</span>

- `<span class="editor-theme-code">disableticketemail = 1</span>`<span style="white-space: pre-wrap;"> — supprime le mail natif Dolibarr au tiers (l'accusé de réception InfraSStudio prend le relais avec un message bien plus soigné) ;</span>
- `<span class="editor-theme-code">notify_tiers_at_create = 0</span>`<span style="white-space: pre-wrap;"> — désactive aussi la notification native du tiers (configurable via la clé </span>`<span class="editor-theme-code">ticket.notify_tiers_at_create</span>`<span style="white-space: pre-wrap;"> du JSON si besoin).</span>

La répartition est donc claire :

<table id="bkmrk-modulep%C3%A9rim%C3%A8treinfra" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.93em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Module

</th><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Périmètre

</th></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**InfraSStudio**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Accusé de réception au visiteur + notification interne </span>

**à la création initiale**

<span style="white-space: pre-wrap;"> du ticket par soumission web.</span>

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">**Gestionnaire de tickets Dolibarr**

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);"><span style="white-space: pre-wrap;">Tout l'échange ultérieur sur le ticket : réponses manuelles d'un agent, mises à jour de statut, fermeture. Utilise ses propres adresses </span>

**From**

<span style="white-space: pre-wrap;">, </span>

**Reply-To**

<span style="white-space: pre-wrap;"> et </span>

**destinataire interne**

<span style="white-space: pre-wrap;"> configurées dans la page d'admin du module.</span>

</td></tr></tbody></table>

<span style="white-space: pre-wrap;">Concrètement : une soumission de formulaire web déclenche exactement deux mails (accusé visiteur + notification équipe, gérés par InfraSStudio), jamais quatre. Quand un agent répond ensuite au ticket depuis Dolibarr, c'est le module natif qui reprend la main — les emails configurés dans </span>**Accueil → Configuration → Modules → Gestionnaire de tickets**<span style="white-space: pre-wrap;"> s'appliquent à ce moment-là.</span>

##### **Rappel automatique en agenda**

Pour les formulaires à fort enjeu commercial (typiquement une demande de démonstration), un événement de rappel peut être créé dans l'agenda. Le délai est configurable, les week-ends peuvent être évités automatiquement, et l'événement est lié au ticket et au tiers pour garantir la traçabilité.

### <span style="color: rgb(35, 111, 161);">Intégrer le formulaire dans un site</span>

Une fois la configuration en place, il reste à exposer le formulaire dans le site. Trois approches sont possibles selon le degré de personnalisation souhaité.

##### **Le shortcode `<strong class="editor-theme-bold editor-theme-code">{{form:name=...}}</strong>`**

La voie la plus simple, surtout pour un rédacteur. Dans n'importe quelle page du site (slot richtext ou directement dans le tpl) :

```
{{form:name=contact-site}}
```

`<span class="editor-theme-code">{{form:name=…}}</span>`<span style="white-space: pre-wrap;"> est un </span>**shortcode**<span style="white-space: pre-wrap;"> résolu au rendu par le moteur de contenu d'InfraSStudio (</span>`<span class="editor-theme-code">StudioContentEngine::applyToPage</span>`<span style="white-space: pre-wrap;">, via le registre de shortcodes — provider </span>`<span class="editor-theme-code">shortcodes/form.shortcode.php</span>`<span style="white-space: pre-wrap;">), qui appelle </span>`<span class="editor-theme-code">infrasstudio_render_public_form</span>`<span style="white-space: pre-wrap;"> pour produire le HTML complet du formulaire — anti-spam et style scopé inclus. Aucune ligne de PHP à toucher côté site. </span>**(Il n'existe pas de hook** `<span class="editor-theme-code">completeHtmlOutput</span>` **; les hooks** `<span class="editor-theme-code">websitepage</span>` **/** `<span class="editor-theme-code">websitenav</span>` **sont déclarés mais ne servent pas à ce rendu.)**

##### **L'helper de rendu unifié**

Pour passer des options dynamiques (référence produit sur une landing, libellés sur mesure, etc.), appeler directement le helper depuis un tpl.php :

```
dol_include_once('/infrasstudio/core/lib/infrasstudio.lib.php');
infrasstudio_render_public_form('contact-site', array(
    'fk_website' => $website->id,
    'fk_page'    => $object->id,
    'extra'      => array('productRef' => 'monproduit'),
));
```

##### **Les starter design templates**

<span style="white-space: pre-wrap;">Quatre templates « clé en main » sont livrés dans </span>`<span class="editor-theme-code">templates/forms/_starter-*.tpl.php</span>`<span style="white-space: pre-wrap;">. Chacun est auto-suffisant (CSS inline scopé, rendu dynamique des champs déclarés dans </span>`<span class="editor-theme-code">config.fields</span>`) — idéal pour démarrer rapidement sur un nouveau site, avant d'éventuellement basculer sur du HTML maison.

<table id="bkmrk-starterstyle-_starte" style="width: 100%; border-collapse: collapse; margin: 1rem 0px; font-size: 0.92em;"><colgroup><col></col><col></col></colgroup><tbody><tr style="background: rgb(25, 5, 45); color: rgb(254, 252, 232);"><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Starter

</th><th class="align-left" style="padding: 0.5rem; text-align: left; border: 1px solid rgb(25, 5, 45);">Style

</th></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">_starter-minimal.tpl.php</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Sobre, labels au-dessus, focus indigo.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">_starter-card.tpl.php</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Carte avec ombre douce et bouton en gradient.

</td></tr><tr><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">_starter-inline.tpl.php</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Inputs alignés horizontalement, compact, idéal newsletter/footer.

</td></tr><tr style="background: rgb(250, 245, 255);"><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">`<span class="editor-theme-code">_starter-modern.tpl.php</span>`

</td><td style="padding: 0.5rem; border: 1px solid rgb(229, 231, 235);">Coins arrondis, fond teinté, gradient bouton, labels uppercase.

</td></tr></tbody></table>

<span style="white-space: pre-wrap;">Le starter choisi dans la modale « + Nouveau formulaire » est automatiquement posé comme </span>`<span class="editor-theme-code">template_override</span>`<span style="white-space: pre-wrap;"> dans la configuration. Il peut être changé à tout moment via l'éditeur JSON avancé.</span>

##### **Conserver un design existant — préfixe `<strong class="editor-theme-bold editor-theme-code">site:</strong>`**

<span style="white-space: pre-wrap;">Pour intégrer le formulaire dans une charte graphique déjà existante (classes CSS du site, structure HTML spécifique), le mécanisme officiel consiste à livrer son propre template depuis le </span>**dossier source du site Dolibarr Website**<span style="white-space: pre-wrap;"> et à le référencer via le préfixe </span>`<span class="editor-theme-code">site:</span>`<span style="white-space: pre-wrap;"> dans la configuration :</span>

1. <span style="white-space: pre-wrap;">Créer un dossier </span>`<span class="editor-theme-code">forms/</span>`<span style="white-space: pre-wrap;"> dans le source du site, soit </span>`<span class="editor-theme-code">DOL_DATA_ROOT/<entity>/website/<ref>/forms/</span>`.
2. <span style="white-space: pre-wrap;">Y déposer un fichier </span>`<span class="editor-theme-code">contact.tpl.php</span>`<span style="white-space: pre-wrap;"> qui réutilise les classes CSS du site et appelle </span>`<span class="editor-theme-code">infrasstudio_render_form_fields()</span>`<span style="white-space: pre-wrap;"> pour générer ses champs (voir la section </span>**Le rendu des champs — helper unique**<span style="white-space: pre-wrap;"> ci-dessous).</span>
3. <span style="white-space: pre-wrap;">Dans le descripteur du formulaire, poser : </span>`<span class="editor-theme-code">"template_override": "site:contact.tpl.php"</span>`.

<span style="white-space: pre-wrap;">Au rendu, le moteur résout vers </span>`<span class="editor-theme-code">DOL_DATA_ROOT/<entity>/website/<ref>/forms/contact.tpl.php</span>`<span style="white-space: pre-wrap;"> en utilisant le </span>`<span class="editor-theme-code">fk_website</span>`<span style="white-space: pre-wrap;"> du contexte. Cette approche permet à chaque site de livrer ses propres templates sans déposer le moindre fichier dans le module générique — qui reste 100% indépendant du métier de chaque client.</span>

<span style="white-space: pre-wrap;">Alternative : si le design impose seulement quelques champs cachés à injecter dans un &lt;form&gt; déjà existant, le helper </span>`<span class="editor-theme-code">infrasstudio_render_form_security($formName, $fkWebsite, $fkPage, $_SERVER['PHP_SELF'])</span>`<span style="white-space: pre-wrap;"> émet d'un seul tenant le </span>`<span class="editor-theme-code">form_name</span>`, le timestamp anti-bot, le honeypot et le captcha conditionnel.

##### **Le rendu des champs — helper unique**

<span style="white-space: pre-wrap;">Quel que soit le template (générique, starter ou </span>`<span class="editor-theme-code">site:</span>`<span style="white-space: pre-wrap;">), le rendu des champs est centralisé dans le helper </span>`<span class="editor-theme-code">infrasstudio_render_form_fields($cfg, $opts)</span>`<span style="white-space: pre-wrap;"> : ordre de déclaration des champs, mapping type → input HTML, hint </span>`<span class="editor-theme-code">autocomplete</span>`, placeholder, et surtout l'**astérisque automatique des champs obligatoires**<span style="white-space: pre-wrap;">. </span>**Un template de formulaire — y compris un template `<strong class="editor-theme-bold editor-theme-code">site:</strong>` — doit appeler ce helper**<span style="white-space: pre-wrap;"> plutôt que coder ses </span>`<span class="editor-theme-code"><input></span>`<span style="white-space: pre-wrap;"> en dur : sinon l'ajout, le réordonnancement ou le passage en obligatoire d'un champ depuis l'éditeur ne se reflète pas côté site.</span>

<span style="white-space: pre-wrap;">Le markup reste entièrement paramétrable pour conserver la charte du site. Options principales : </span>`<span class="editor-theme-code">row_class</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">label_class</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">input_class</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">textarea_class</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">req_html</span>`<span style="white-space: pre-wrap;"> (markup de l'astérisque), </span>`<span class="editor-theme-code">id_prefix</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">label_wrap</span>`<span style="white-space: pre-wrap;"> (libellé englobant l'input), </span>`<span class="editor-theme-code">show_label</span>`<span style="white-space: pre-wrap;"> (libellés masqués pour les formulaires compacts), </span>`<span class="editor-theme-code">exclude</span>`<span style="white-space: pre-wrap;"> (champs cachés gérés à part, ex. </span>`<span class="editor-theme-code">product_ref</span>`<span style="white-space: pre-wrap;">), </span>`<span class="editor-theme-code">labels</span>`<span style="white-space: pre-wrap;"> (overrides i18n </span>`<span class="editor-theme-code">field_<clé></span>`<span style="white-space: pre-wrap;"> / </span>`<span class="editor-theme-code">placeholder_<clé></span>`).

<span style="white-space: pre-wrap;">Exemple dans un template </span>`<span class="editor-theme-code">site:</span>`<span style="white-space: pre-wrap;"> réutilisant les classes CSS du site :</span>

```
print infrasstudio_render_form_fields($cfg, array(
    'row_class'   => 'form-row',
    'label_class' => 'form-label',
    'input_class' => 'form-input',
    'req_html'    => ' <span class="req">*</span>',
    'id_prefix'   => '',
));
```

### <span style="color: rgb(35, 111, 161);">Suivre et auditer les soumissions</span>

<span style="white-space: pre-wrap;">Chaque soumission acceptée est persistée dans </span>`<span class="editor-theme-code">llx_infrasstudio_form_submission</span>`<span style="white-space: pre-wrap;"> avec son contenu sanitisé, l'adresse IP d'origine, l'agent utilisateur, la page de provenance et la trace du consentement RGPD. Le viewer d'administration (</span>**Outils → InfraS → Soumissions**) permet de filtrer par formulaire, statut ou plage de dates, d'ouvrir le détail complet d'une soumission et d'accéder en un clic au tiers, au contact, au ticket et à l'événement d'agenda qui en ont découlé. Cette traçabilité complète est précieuse à la fois pour le suivi commercial et pour répondre aux demandes RGPD des visiteurs.

### <span style="color: rgb(35, 111, 161);">Récapitulatif</span>

<span style="white-space: pre-wrap;">Le moteur de formulaires d'InfraSStudio transforme un simple formulaire web en véritable point d'entrée du CRM. Configurable sans code, sécurisé par défaut et entièrement intégré à l'écosystème Dolibarr, il évite la fragmentation des outils tout en gardant la souplesse nécessaire à chaque projet. Pour aller plus loin, voir le Chapitre 28 (constantes), le Chapitre 31 (modèle SQL des trois tables </span>`<span class="editor-theme-code">llx_infrasstudio_form_*</span>`) et l'Annexe B (FAQ) pour les questions opérationnelles courantes.