# 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. ### Architecture du moteur 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.
Pièce Rôle
**Endpoint unique** `public/forms/submit.php` reçoit toutes les soumissions. Le formulaire est identifié par son nom inséré en champ caché `form_name`.
**Descripteur JSON** Une ligne dans `llx_infrasstudio_form_config` par formulaire. Décrit les champs, les règles de validation, les paramètres anti-spam et les adapters à exécuter.
**Pipeline d'adapters** Six étapes activables à la carte : validation, anti-spam, tiers, contact, ticket, notification, agenda.
##### **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.
Adapter Effet sur la soumission
**antispam** Honeypot, délai minimum de remplissage, rate-limit par adresse IP, captcha délégué au gestionnaire Dolibarr actif.
**tiers** Recherche ou création d'une société dans `llx_societe`. Application d'une catégorie et d'une origine.
**contact** Recherche ou création d'un contact dans `llx_socpeople`, libre ou rattaché au tiers.
**ticket** Ouverture d'un ticket Dolibarr avec sujet, message, catégorie et sévérité.
**notification** Envoi d'un email interne à l'équipe commerciale et d'un accusé de réception au visiteur.
**agenda** Création d'un événement de rappel lié au tiers et au ticket.
### Configurer un formulaire Deux interfaces complémentaires sont disponibles. **L'administration avancée** se trouve dans **Outils → InfraS → Formulaires** : grille des configurations, statistiques de soumission, accès au descripteur JSON brut. **L'éditeur Studio** propose désormais un onglet **Formulaires** avec un inspector inline qui couvre la majorité des réglages courants sans repasser par l'administration Dolibarr. ##### **Créer un nouveau formulaire** Le bouton **« + Nouveau formulaire »** de l'onglet Formulaires de l'éditeur Studio ouvre une modale en quatre champs : - le **libellé affiché en administration** (facultatif) ; - l'**identifiant technique** (a-z, 0-9, tiret, underscore — utilisé dans le HTML, unique par entité) ; - le **type** (**contact**, **newsletter**, **demo** ou **generic**) — le type définit les champs par défaut et le pipeline par défaut ; - un **modèle de design** (facultatif) — voir la section **Les starter design templates** ci-dessous. 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** Dans l'onglet **Formulaires** de l'éditeur Studio, la section **Champs** permet d'**ajouter**, de **réordonner** (boutons monter / descendre) et de **supprimer** 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 **Obligatoire** : lorsqu'il est activé, un astérisque `*` 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. ##### **Supprimer un formulaire** La section **« Zone dangereuse »** en bas de l'inspector expose un bouton **Supprimer ce formulaire**. La suppression efface uniquement la configuration : les soumissions déjà enregistrées dans `llx_infrasstudio_form_submission` sont conservées (traçabilité RGPD préservée). Une modale de confirmation Studio garde le doigt sur le bouton — la fenêtre `confirm()` native du navigateur n'est jamais utilisée. Le même contrôle est disponible depuis **Outils → InfraS → Formulaires** via le bouton **Supprimer** de chaque ligne. ##### **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" } ``` La clé `template_override` est facultative — sans elle, le moteur utilise le template par défaut du type. Voir la section **Intégrer le formulaire dans un site** pour les trois modes de résolution. ##### **Tester un formulaire avant mise en ligne** La fiche admin de chaque formulaire (**Outils → InfraS → Formulaires** → ouvrir un formulaire) expose un bouton **« Tester ce formulaire »** 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. Les entités créées en mode test (Société, Contact, Ticket, événement d'agenda) sont : - **marquées explicitement** : leur libellé est préfixé `[TEST]` pour être reconnaissables au premier coup d'œil dans Dolibarr ; - **flaguées en base** : la soumission correspondante porte `is_test=1` dans `llx_infrasstudio_form_submission` ; - **purgeables en un clic** : le bouton **Purger les données de test** 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. En mode test, le captcha est **volontairement bypassé** 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. 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 **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. ### Connecter le formulaire à votre CRM 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** 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 `origine` renseigné depuis le dictionnaire `c_input_reason`). 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 (`llx_c_ticket_category`, `llx_c_ticket_severity`). ##### **Notification et accusé de réception** Deux emails partent automatiquement à chaque soumission acceptée : une **notification interne** adressée à l'équipe pour traiter la demande, et un **accusé de réception** 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 **Pipeline**, section **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.
Champ Effet
**Email destinataire admin** Adresse(s) qui reçoivent l'alerte interne. Plusieurs destinataires séparés par une virgule. Laisser vide pour désactiver la notification interne.
**Modèle du sujet admin** Objet du mail interne. Accepte les variables `{{payload.X}}` , `{{form_name}}` , `{{submission_id}}` .
**Corps de la notification admin** 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).
**Le corps admin est du HTML** Interrupteur (toggle). Si activé, le corps est interprété comme du HTML ; sinon il part en texte brut et les balises apparaissent telles quelles.
**Champ payload utilisé comme Reply-To** Nom du champ contenant l'email du visiteur (défaut : `email` ). Un clic sur **Répondre** dans la messagerie répondra directement au visiteur, pas à l'expéditeur technique.
**Activer l'accusé de réception** Interrupteur. Si activé, le visiteur reçoit un mail de confirmation à l'adresse qu'il a saisie.
**Champ payload de l'adresse visiteur** Nom du champ du formulaire contenant l'adresse du visiteur. Par défaut `email` .
**Sujet de l'accusé de réception** Objet du mail reçu par le visiteur. **Ignoré** si un modèle est sélectionné ci-dessous.
**Corps de l'accusé de réception** Corps du mail reçu par le visiteur. **Ignoré** si un modèle est sélectionné. Laisser vide pour un texte générique de remerciement.
**Le corps de l'accusé est du HTML** Interrupteur (toggle) équivalent côté visiteur.
**Modèle d'accusé de réception** Liste déroulante des modèles d'email Dolibarr de type `infrasstudio_form` . Quand un modèle est sélectionné, il prend la main sur les champs **Sujet** et **Corps** ci-dessus. Avantage : le texte est centralisé dans **Configuration → Emails → Modèles d'e-mails** , partagé entre tous les formulaires qui pointent dessus.
**Adresse expéditeur (From) / Nom expéditeur (From)** Surcharge per-formulaire de l'adresse et du nom apparaissant comme expéditeur des deux mails. Vides : utilise `MAIN_MAIL_EMAIL_FROM` et le nom de la société configurée dans Dolibarr.
###### **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.
Variable Valeur
`{{payload.X}}` Valeur du champ `X` saisi par le visiteur. Raccourci : `{{X}}` .
`{{form_name}}` Identifiant technique du formulaire actif.
`{{submission_id}}` Numéro de la soumission, utile pour bâtir un lien admin direct.
`{{ip}}` IP du visiteur.
`{{mysoc.name}}` , `{{mysoc.email}}` , `{{mysoc.phone}}` Coordonnées de la société configurée dans Dolibarr.
`{{config.X}}` Clé de premier niveau du JSON config courant.
###### **Exemple — notification interne mise en forme** Sujet : ``` [{{form_name}}] Nouvelle demande de {{payload.name}} ({{payload.company}}) ``` Corps HTML (interrupteur **Le corps admin est du HTML** activé) : ```

Nouvelle demande de contact

Formulaire : {{form_name}} · Soumission #{{submission_id}}
Nom{{payload.name}}
Société{{payload.company}}
Email{{payload.email}}

Message

{{payload.message}}
IP : {{ip}} · Reçu via {{mysoc.name}}
``` 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** 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 `TICKET_CREATE` au tiers et sa propre alerte interne. Pour éviter les doublons, InfraSStudio positionne deux drapeaux dans le contexte de création : - `disableticketemail = 1` — supprime le mail natif Dolibarr au tiers (l'accusé de réception InfraSStudio prend le relais avec un message bien plus soigné) ; - `notify_tiers_at_create = 0` — désactive aussi la notification native du tiers (configurable via la clé `ticket.notify_tiers_at_create` du JSON si besoin). La répartition est donc claire :
Module Périmètre
**InfraSStudio** Accusé de réception au visiteur + notification interne **à la création initiale** du ticket par soumission web.
**Gestionnaire de tickets Dolibarr** Tout l'échange ultérieur sur le ticket : réponses manuelles d'un agent, mises à jour de statut, fermeture. Utilise ses propres adresses **From** , **Reply-To** et **destinataire interne** configurées dans la page d'admin du module.
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 **Accueil → Configuration → Modules → Gestionnaire de tickets** s'appliquent à ce moment-là. ##### **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é. ### Intégrer le formulaire dans un site 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 `{{form:name=...}}`** 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}} ``` `{{form:name=…}}` est un **shortcode** résolu au rendu par le moteur de contenu d'InfraSStudio (`StudioContentEngine::applyToPage`, via le registre de shortcodes — provider `shortcodes/form.shortcode.php`), qui appelle `infrasstudio_render_public_form` pour produire le HTML complet du formulaire — anti-spam et style scopé inclus. Aucune ligne de PHP à toucher côté site. **(Il n'existe pas de hook** `completeHtmlOutput` **; les hooks** `websitepage` **/** `websitenav` **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** Quatre templates « clé en main » sont livrés dans `templates/forms/_starter-*.tpl.php`. Chacun est auto-suffisant (CSS inline scopé, rendu dynamique des champs déclarés dans `config.fields`) — idéal pour démarrer rapidement sur un nouveau site, avant d'éventuellement basculer sur du HTML maison.
Starter Style
`_starter-minimal.tpl.php` Sobre, labels au-dessus, focus indigo.
`_starter-card.tpl.php` Carte avec ombre douce et bouton en gradient.
`_starter-inline.tpl.php` Inputs alignés horizontalement, compact, idéal newsletter/footer.
`_starter-modern.tpl.php` Coins arrondis, fond teinté, gradient bouton, labels uppercase.
Le starter choisi dans la modale « + Nouveau formulaire » est automatiquement posé comme `template_override` dans la configuration. Il peut être changé à tout moment via l'éditeur JSON avancé. ##### **Conserver un design existant — préfixe `site:`** 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 **dossier source du site Dolibarr Website** et à le référencer via le préfixe `site:` dans la configuration : 1. Créer un dossier `forms/` dans le source du site, soit `DOL_DATA_ROOT//website//forms/`. 2. Y déposer un fichier `contact.tpl.php` qui réutilise les classes CSS du site et appelle `infrasstudio_render_form_fields()` pour générer ses champs (voir la section **Le rendu des champs — helper unique** ci-dessous). 3. Dans le descripteur du formulaire, poser : `"template_override": "site:contact.tpl.php"`. Au rendu, le moteur résout vers `DOL_DATA_ROOT//website//forms/contact.tpl.php` en utilisant le `fk_website` 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. Alternative : si le design impose seulement quelques champs cachés à injecter dans un <form> déjà existant, le helper `infrasstudio_render_form_security($formName, $fkWebsite, $fkPage, $_SERVER['PHP_SELF'])` émet d'un seul tenant le `form_name`, le timestamp anti-bot, le honeypot et le captcha conditionnel. ##### **Le rendu des champs — helper unique** Quel que soit le template (générique, starter ou `site:`), le rendu des champs est centralisé dans le helper `infrasstudio_render_form_fields($cfg, $opts)` : ordre de déclaration des champs, mapping type → input HTML, hint `autocomplete`, placeholder, et surtout l'**astérisque automatique des champs obligatoires**. **Un template de formulaire — y compris un template `site:` — doit appeler ce helper** plutôt que coder ses `` 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. Le markup reste entièrement paramétrable pour conserver la charte du site. Options principales : `row_class`, `label_class`, `input_class`, `textarea_class`, `req_html` (markup de l'astérisque), `id_prefix`, `label_wrap` (libellé englobant l'input), `show_label` (libellés masqués pour les formulaires compacts), `exclude` (champs cachés gérés à part, ex. `product_ref`), `labels` (overrides i18n `field_` / `placeholder_`). Exemple dans un template `site:` réutilisant les classes CSS du site : ``` print infrasstudio_render_form_fields($cfg, array( 'row_class' => 'form-row', 'label_class' => 'form-label', 'input_class' => 'form-input', 'req_html' => ' *', 'id_prefix' => '', )); ``` ### Suivre et auditer les soumissions Chaque soumission acceptée est persistée dans `llx_infrasstudio_form_submission` 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 (**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. ### Récapitulatif 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 `llx_infrasstudio_form_*`) et l'Annexe B (FAQ) pour les questions opérationnelles courantes.