Formulaires
Le formulaire statique (vn-sform) avec tous ses marqueurs, l'envoi PHP commun (mailer.php, config.php, recipients.php, SMTP), la protection anti-spam, ainsi que VN Form Editor avec le Form Renderer (types de champs, règles, enregistrement, intégration).
Vue d'ensemble#
Il existe deux façons d'obtenir un formulaire fonctionnel. Les deux envoient via le même PHP (mailer.php), dont les identifiants sont générés par le programme lors de l'export.
| Voie | Emplacement du formulaire | Quand la choisir |
|---|---|---|
Formulaire statique (vn-sform) | HTML final dans le bloc (champs directement dans le template) | Formulaires de contact dans les thèmes et les blocs ; tous les textes modifiables d'un clic ; apparence via le panneau et le CSS |
Form Renderer (vn-formrender) | Un fichier JSON généré par VN Form Editor ; le bloc ne construit le formulaire que dans le navigateur | Formulaires avec règles (afficher/masquer), plusieurs étapes, signature, hCaptcha |
Prérequis : le site se trouve sur un serveur avec PHP. Les pages elles-mêmes peuvent s'appeler .html ; seul le PHP dans assets/vn-formrender/ doit être exécuté. L'adresse d'expédition et le serveur de messagerie (SMTP) se règlent dans le programme (voir Paramètres SMTP).
Le formulaire statique : vn-sform#
Structure de base#
Syntaxe
<section class="vn-sform">
<vn-parameters> … </vn-parameters>
<div class="vn-sform-inner">
<form class="vn-sform-form" novalidate
data-recipient="{{recipient}}" data-subject="{{subject}}"
data-success="{{successText}}" data-thankyou="{{thankYouUrl}}"
data-mailer="assets/vn-formrender/mailer.php" aria-label="Kontaktformular">
<div class="vn-sform-fields">
</div>
<div class="vn-sform-hp" aria-hidden="true"><label>Bitte leer lassen<input type="text" name="website" tabindex="-1" autocomplete="off"></label></div>
<button type="submit" class="vn-sform-enter" tabindex="-1" aria-hidden="true"></button>
<div class="vn-sform-status" role="status" aria-live="polite" hidden></div>
</form>
</div>
</section>(d'après src/vn-sform.js ; la même forme est utilisée par themes/vn-handwerk-src/components/kontakt1 et gallery-content/vn-app-theme/src/components/signup1)
| Élément | Obligatoire | Rôle |
|---|---|---|
form.vn-sform-form | oui | Marqueur de reconnaissance. Seul un <form> portant cette classe est repris par le script et reconnu par l'export (class="… vn-sform-form …") |
div.vn-sform-field[data-type] | oui, pour chaque champ | Un champ avec son libellé ; data-type détermine l'évaluation |
.vn-sform-label | oui | Libellé ; son texte devient le nom du champ dans l'e-mail |
div.vn-sform-hp avec input[name="website"] | oui | Pot de miel (honeypot, piège à spam), voir Protection anti-spam |
button.vn-sform-enter | recommandé | Bouton d'envoi invisible, pour que Entrée dans un champ envoie le formulaire |
div.vn-sform-status | oui | Zone de message (hidden), voir Messages |
a[data-vn-sform-submit] | oui | Le bouton d'envoi |
novalidate | oui | La validation est assurée par le script (messages d'erreur propres sous les champs) |
L'élément form : attributs data#
| Attribut | Type/valeurs | Défaut | Signification |
|---|---|---|---|
data-recipient | adresse e-mail | — | Destinataire ; exactement une adresse (voir Destinataires) |
data-subject | texte | Neue Nachricht über die Webseite | Objet de l'e-mail (150 caractères au plus, sauts de ligne supprimés) |
data-success | texte | Danke für deine Nachricht! (avec lang="en" : Thank you for your message!) | Message après un envoi réussi |
data-thankyou | adresse | vide | Page de remerciement : si elle est définie, le visiteur y est redirigé au lieu de voir le message |
data-mailer | chemin | assets/vn-formrender/mailer.php | Adresse du script d'envoi, relative à la page ; captcha.php en est déduit (mailer.php… → captcha.php) |
data-vn-sform-ready | 1 | — | Posé par le script : le formulaire est initialisé (ne pas le définir à la main) |
Types de champs#
Chaque champ est un div.vn-sform-field avec data-type. Le script collecte tous les .vn-sform-field[data-type], y lit le libellé (.vn-sform-label) et le premier élément de saisie (input:not([type=radio]), textarea, select).
data-type | Élément de saisie | Valeur dans l'e-mail |
|---|---|---|
text, tel, url, number, date | input.vn-sform-input[type=…] | texte saisi (sans espaces superflus) |
email | input[type=email] | texte ; la première adresse e-mail valide devient Reply-To et destinataire de la copie à l'expéditeur |
textarea | textarea.vn-sform-input.vn-sform-textarea | texte |
select | select.vn-sform-input.vn-sform-select | value choisie |
radio | div.vn-sform-choices avec plusieurs input[type=radio] (même name) | value choisie ; obligatoire si le premier bouton radio porte required |
checkbox | input[type=checkbox] | Ja ou Nein |
consent | input[type=checkbox][required] (protection des données) | Ja/Nein ; toujours obligatoire |
copytosender | input[type=checkbox][data-vn-copytosender] | absent de l'e-mail ; active la copie à l'expéditeur |
file | input.vn-sform-file[type=file] | fichier en pièce jointe ; nom et taille dans l'e-mail |
captcha | voir Question de sécurité | absent de l'e-mail |
heading | h3.vn-sform-heading (le champ s'appelle vn-sform-field vn-sform-heading-wrap) | ignoré |
submit | a.btn.vn-sform-submit[data-vn-sform-submit] | ignoré |
(sans champ) input[type=hidden] | name, value, data-label | entrée sous data-label (sinon name), si une valeur est présente |
Exemples (d'après src/vn-sform.js) :
<div class="vn-sform-field" data-type="text" style="--span:6">
<p class="vn-sform-label" id="{{vn-id}}-f1-l">Name<span class="vn-sform-req" aria-hidden="true"> *</span></p>
<input class="vn-sform-input" type="text" id="{{vn-id}}-f1" name="f1" aria-labelledby="{{vn-id}}-f1-l" required>
</div>
<div class="vn-sform-field" data-type="select" style="--span:12">
<p class="vn-sform-label" id="{{vn-id}}-f4-l">Anliegen</p>
<select class="vn-sform-input vn-sform-select" id="{{vn-id}}-f4" name="f4" aria-labelledby="{{vn-id}}-f4-l">
<option value=""></option><option value="Bad">Bad</option><option value="Heizung">Heizung</option>
</select>
</div>
<div class="vn-sform-field" data-type="radio" style="--span:12">
<p class="vn-sform-label" id="{{vn-id}}-f5-l">Wie dringend?</p>
<div class="vn-sform-choices" role="radiogroup" aria-labelledby="{{vn-id}}-f5-l">
<label class="vn-sform-choice"><input type="radio" name="f5" value="Normal" required><span>Normal</span></label>
<label class="vn-sform-choice"><input type="radio" name="f5" value="Dringend"><span>Dringend</span></label>
</div>
</div>
<div class="vn-sform-field" data-type="consent" style="--span:12">
<div class="vn-sform-check">
<input type="checkbox" id="{{vn-id}}-f6" name="f6" aria-labelledby="{{vn-id}}-f6-l" required>
<p class="vn-sform-label vn-sform-label-inline" id="{{vn-id}}-f6-l">Ich habe die <a href="/datenschutz" target="_blank" rel="noopener">Datenschutzerklärung</a> gelesen und bin einverstanden.</p>
</div>
</div>Grille : --span#
La grille des champs compte 12 colonnes (.vn-sform-fields { display:grid; grid-template-columns: repeat(12, 1fr) }). La largeur d'un champ est indiquée par une variable de style sur le champ.
| Indication | Valeur | Signification |
|---|---|---|
style="--span:N" | 1–12 | Nombre de colonnes ; 6 = demi-largeur, 12 = ligne entière |
| depuis l'éditeur de formulaires | width en % | devient --span = round(width/100*12) (1–12 ; valeur invalide = 12) |
| Mobile (moins de 640 px) | — | chaque champ occupe 12 colonnes |
Les thèmes avec grille Bootstrap (row g-3, col-sm-6) fonctionnent aussi : le script ne lit que .vn-sform-field[data-type], pas les colonnes (exemple kontakt1 dans le thème VN Handwerk).
Champs obligatoires#
Un champ est obligatoire grâce à l'attribut required sur l'élément de saisie. L'astérisque est purement visuel (<span class="vn-sform-req" aria-hidden="true"> *</span> dans le libellé) ; le script le retire du nom de champ dans l'e-mail.
| Contrôle (dans le navigateur, avant l'envoi) | Message |
|---|---|
| Champ obligatoire vide | Bitte ausfüllen. |
| Champ e-mail avec adresse invalide | Bitte eine gültige E-Mail-Adresse eingeben. |
| Case obligatoire non cochée | Bitte bestätigen. |
Groupe radio sans choix (premier radio required) | Bitte auswählen. |
| Fichier obligatoire manquant | Bitte eine Datei wählen. |
| Fichier de plus de 3 Mo | Die Datei ist zu groß (max. 3 MB). |
| Champ de calcul vide | Bitte ausfüllen. |
Les champs en erreur reçoivent la classe vn-sform-invalid ; un <p class="vn-sform-error"> figure sous eux. Le premier champ en erreur reçoit le focus. Les messages du tableau sont codés en dur en allemand dans le script ; seuls les textes de la question de sécurité mathématique et le message de réussite de secours suivent le lang de <html> (en = anglais). Pour des textes propres de réussite et de redirection, utilisez data-success et data-thankyou.
Bouton d'envoi#
Syntaxe
<div class="vn-sform-field vn-sform-submit-wrap" data-type="submit">
<a class="btn btn-primary vn-sform-submit" href="#" role="button" data-vn-sform-submit>Absenden</a>
</div>| Attribut | Signification |
|---|---|
data-vn-sform-submit | Un clic envoie le formulaire (preventDefault) ; le script pose alors vn-sform-busy sur le bouton (pas de double clic) |
a.btn | Le bouton est un bouton normal, modifiable d'un clic (couleur, libellé, icône ; voir Boutons) |
.vn-sform-enter | button[type=submit] invisible supplémentaire, pour que Entrée dans un champ envoie le formulaire |
Protection anti-spam : pot de miel#
Le champ input[name="website"] dans div.vn-sform-hp est invisible pour les humains (sorti de l'écran, tabindex="-1"). Si un robot le remplit, mailer.php feint le succès sans rien envoyer (les robots ne remarquent aucune différence).
| Protection | Où | Description |
|---|---|---|
Pot de miel (honeypot) website | Formulaire + serveur | Non vide = faux succès silencieux |
| Question de sécurité mathématique | Type de champ captcha | Uniquement si le formulaire contient le champ |
| Limitation par IP | Serveur | 5 requêtes par 10 minutes au plus par adresse de visiteur (réponse Zu viele Anfragen, bitte später erneut versuchen.) |
| Limitation de taille | Serveur | 40 champs au plus, 8000 caractères au total (noms + valeurs) |
| Liste des destinataires | Serveur | uniquement les adresses de recipients.php (Destinataires) |
Question de sécurité mathématique#
Syntaxe
<div class="vn-sform-field" data-type="captcha" style="--span:12">
<p class="vn-sform-label" id="{{vn-id}}-f7-l">Sicherheitsabfrage</p>
<div class="vn-sform-captcha">
<span class="vn-sform-captcha-q" data-vn-captcha-q>3 + 4 = ?</span>
<input class="vn-sform-input vn-sform-captcha-a" type="text" inputmode="numeric" autocomplete="off"
data-vn-captcha-answer id="{{vn-id}}-f7" name="f7" aria-labelledby="{{vn-id}}-f7-l" required>
<input type="hidden" data-vn-captcha-token>
</div>
</div>| Attribut | Signification |
|---|---|
data-vn-captcha-q | Le script y écrit l'opération (a + b = ?, nombres de 1 à 9) |
data-vn-captcha-answer | Le champ de réponse |
data-vn-captcha-token | Champ caché pour le jeton signé |
Déroulement : le script récupère la question et le jeton auprès de captcha.php (?t=<heure>, sans mise en cache). Le jeton est base64({a,b,exp}) + "." + HMAC-SHA256, signé avec la clé secrète de config.php (hmac_secret), valable 10 minutes ; le résultat n'apparaît nulle part en clair. mailer.php vérifie la signature, l'expiration et la somme. Après chaque envoi, une nouvelle opération est chargée. Si captcha.php est inaccessible, la question affiche nicht verfügbar (indisponible).
Messages et redirection#
| Cas | Affichage |
|---|---|
Succès (HTTP 200, success: true) | Sans data-thankyou : le formulaire est vidé, .vn-sform-status.vn-sform-ok affiche data-success (sinon la réponse du serveur, sinon Danke für deine Nachricht!). Avec data-thankyou : redirection vers cette page |
| Erreur du serveur | .vn-sform-status.vn-sform-fail avec le message du serveur (par exemple Zu viele Anfragen …) |
| Erreur réseau | Das Formular konnte nicht gesendet werden. Bitte später erneut versuchen. |
La zone .vn-sform-status est hidden par défaut. Les classes vn-sform-ok et vn-sform-fail déterminent la couleur et la bordure.
Envoi de fichiers#
Un champ data-type="file" envoie le fichier en pièce jointe de l'e-mail. Lorsque des fichiers sont choisis, le script envoie multipart/form-data au lieu de JSON.
| Limite | Valeur | Où |
|---|---|---|
| Taille par fichier dans le navigateur | 3 Mo | vn-sform.js (message au moment du choix) |
| Taille par fichier sur le serveur | 8 Mo | mailer.php (Datei zu groß (max. 8 MB).) |
| Toutes les pièces jointes ensemble | 15 Mo | mailer.php |
| Types | aucune restriction | Le nom de fichier est réduit à son basename ; le fichier n'est pas enregistré, seulement joint à l'e-mail |
Copie à l'expéditeur#
Le champ data-type="copytosender" (case à cocher avec data-vn-copytosender) active une copie : l'expéditeur reçoit le même e-mail à l'adresse Reply-To (la première adresse e-mail valide d'un champ e-mail), avec l'objet complété par « (Kopie deiner Nachricht) ». L'échec de la copie ne signale aucune erreur.
Format des données vers le serveur#
Le script envoie du JSON sans fichiers (Content-Type: application/json) :
{
"recipient": "info@example.com",
"subject": "Neue Nachricht über die Webseite",
"reply_to": "kunde@example.com",
"copy_to_sender": false,
"website": "",
"captcha_answer": "",
"captcha_token": "",
"fields": { "Name": "Max", "E-Mail": "kunde@example.com", "Nachricht": "…" }
}Avec fichiers : multipart/form-data avec les champs recipient, subject, reply_to, copy_to_sender (1 ou vide), website, captcha_answer, captcha_token, fields_json (texte JSON des mêmes fields), files[], file_labels[]. La réponse est toujours du JSON : { "success": true|false, "message": "…" } (HTTP 200 en cas de succès, sinon 400/500).
Les clés de fields sont les libellés (sans astérisque). Les libellés identiques sont maintenus distincts par des espaces ajoutés.
Panneau des propriétés du bloc#
Le bloc fini « Formulaire (statique) » apporte ces champs (name dans vn-parameters) ; ils ne sont nécessaires que si vous construisez votre propre bloc avec un panneau :
Champ (name) | Type | Signification |
|---|---|---|
recipient | Texte | Destinataire (vers data-recipient) |
subject | Texte | Objet (data-subject) |
successText | Texte | Message de réussite (data-success) |
thankYouUrl | Texte | Page de remerciement (data-thankyou) |
padding, maxWidth, align, gap | Nombres/choix | Marge, largeur maximale, alignement, espacement des champs |
fieldStyle | outline, filled, line | Apparence des champs |
radius, fieldSize | Nombre, sm/md/lg | Arrondi, taille |
borderColor, fieldBg, focusColor | Couleur | Bordure, arrière-plan, focus |
bgColor, labelColor, textColor, errorColor, okColor | Couleur | Couleurs de fond et de texte |
btnAlign | left, center, right, full | Alignement du bouton d'envoi |
Exemple : formulaire de contact dans un thème#
Extrait de themes/vn-handwerk-src/components/kontakt1/template.html (abrégé). Il utilise des classes Bootstrap pour la grille et masque visuellement les libellés (visually-hidden), mais affiche des textes indicatifs (placeholders) :
<form class="vn-sform-form" novalidate data-recipient="{{recipient}}" data-subject="{{subject}}"
data-success="{{successText}}" data-thankyou="" data-mailer="assets/vn-formrender/mailer.php"
aria-label="Kontaktformular">
<div class="row g-3">
<div class="col-sm-6 vn-sform-field" data-type="text">
<p class="vn-sform-label visually-hidden" id="{{vn-id}}-f1-l">Ihr Name<span class="vn-sform-req" aria-hidden="true"> *</span></p>
<input type="text" class="form-control hw-in vn-sform-input" placeholder="Ihr Name"
id="{{vn-id}}-f1" name="f1" aria-labelledby="{{vn-id}}-f1-l" required>
</div>
<div class="col-12 vn-sform-field" data-type="email">
<p class="vn-sform-label visually-hidden" id="{{vn-id}}-f3-l">E-Mail-Adresse<span class="vn-sform-req" aria-hidden="true"> *</span></p>
<input type="email" class="form-control hw-in vn-sform-input" placeholder="E-Mail-Adresse"
id="{{vn-id}}-f3" name="f3" aria-labelledby="{{vn-id}}-f3-l" autocomplete="email" required>
</div>
<div class="col-12 vn-sform-field" data-type="textarea">
<p class="vn-sform-label visually-hidden" id="{{vn-id}}-f5-l">Ihre Nachricht<span class="vn-sform-req" aria-hidden="true"> *</span></p>
<textarea class="form-control hw-in vn-sform-input vn-sform-textarea" rows="4" placeholder="Ihre Nachricht"
id="{{vn-id}}-f5" name="f5" aria-labelledby="{{vn-id}}-f5-l" required></textarea>
</div>
<div class="col-12 vn-sform-field vn-sform-submit-wrap" data-type="submit">
<a href="#" role="button" class="btn hw-b hw-b-solid w-100" data-vn-sform-submit>Anfrage senden</a>
</div>
</div>
<div class="vn-sform-hp" aria-hidden="true"><label>Bitte leer lassen<input type="text" name="website" tabindex="-1" autocomplete="off"></label></div>
<button type="submit" class="vn-sform-enter" tabindex="-1" aria-hidden="true"></button>
<div class="vn-sform-status" role="status" aria-live="polite" hidden></div>
</form>Formulaire statique issu de l'éditeur de formulaires#
Le bloc « Formulaire (statique) » (createSformBlockEntry) reprend, sous forme de HTML final, les champs d'un formulaire construit dans VN Form Editor.
| Groupe | Types de champs |
|---|---|
| Repris | text, textarea, email, tel, url, number, date, select, radio, checkbox, file, hidden, heading, submit, consent, copytosender, captcha |
| Non repris (uniquement dans le Form Renderer) | hcaptcha, signature (signature), linkdisplay (affichage de lien), règles, formulaires en plusieurs étapes |
Sans champ d'envoi, le bloc ajoute un bouton « Envoyer ». Les numéros de champ (f1, f2 …) sont réattribués de façon continue ; {{ dans le texte d'un champ est écrit {{ afin que le texte ne soit jamais interprété comme un espace réservé.
Côté serveur#
mailer.php#
Le script d'envoi commun assets/vn-formrender/mailer.php (PHPMailer, SMTP). La réponse est toujours du JSON { success, message }.
| Étape | Contrôle | Réponse en cas d'infraction |
|---|---|---|
| 1 | La méthode doit être POST | Ungültige Anfrage-Methode. |
| 2 | ../vn-shared/config.php doit exister et contenir $hmac_secret, $smtp_host, $smtp_username, $smtp_password | Formular ist noch nicht konfiguriert … |
| 3 | Lecture du contenu (JSON ou multipart) | Ungültige Anfrage. |
| 4 | Pot de miel website non vide | Le succès est simulé, rien n'est envoyé |
| 5 | hCaptcha ou captcha mathématique (selon ce qui a été envoyé) | Sicherheitsabfrage … / hCaptcha-Prüfung fehlgeschlagen … |
| 6 | Limitation par IP : 5 requêtes par 10 minutes (fichier dans sys_get_temp_dir()) | Zu viele Anfragen, bitte später erneut versuchen. |
| 7 | recipient doit être une seule adresse e-mail valide | Kein gültiger Empfänger konfiguriert. |
| 8 | L'adresse doit figurer dans recipients.php (si le fichier existe) | Dieser Empfänger ist für das Formular nicht freigegeben. |
| 9 | Il doit y avoir des champs ou des fichiers ; 40 champs et 8000 caractères au plus | Keine Formulardaten übermittelt. / Eingabe zu lang. |
| 10 | Fichiers : 8 Mo par fichier, 15 Mo au total, uniquement de vrais envois | Datei zu groß … / Anhänge zusammen zu groß … |
| 11 | Objet : 150 caractères au plus, \r/\n supprimés (injection d'en-têtes) | — |
| 12 | E-mail : tableau HTML (nom du champ, valeur ; valeurs avec htmlspecialchars et nl2br) et version texte ; Reply-To seulement avec une adresse valide | Mail konnte nicht versendet werden, bitte später erneut versuchen. |
| 13 | Copie facultative à l'expéditeur | Les erreurs de la copie sont ignorées |
Les champs vides ne sont pas repris dans l'e-mail. Les erreurs PHP fatales sont interceptées par un gestionnaire d'arrêt, qui renvoie du JSON au lieu d'une page 500 vide (avec le champ debug et l'emplacement de l'erreur).
Vérifié (PHP 8.3, serveur de test dédié, SMTP volontairement inaccessible) : plusieurs adresses séparées par une virgule → Kein gültiger Empfänger konfiguriert. ; adresse étrangère avec un recipients.php présent → non autorisée ; pot de miel → 200 avec faux succès ; jeton de captcha erroné → Sicherheitsabfrage ungültig … ; captcha.php renvoie {question, token} ; appel valide → Mail konnte nicht versendet werden ….
Destinataires#
Le destinataire figure dans la page (data-recipient) et est envoyé par le navigateur. Sans protection, n'importe qui pourrait, avec sa propre requête, écrire à des adresses quelconques via votre accès de messagerie. C'est pourquoi l'export crée le fichier assets/vn-formrender/recipients.php.
Syntaxe
<?php
// Von VN-Designer beim Export erzeugt: Empfänger der Formulare dieser Seite (mailer.php sendet nur an diese Adressen).
return array(
'info@example.com',
);| Règle | Description |
|---|---|
| Contenu | toutes les valeurs data-recipient de toutes les pages exportées et, à partir de la version 1.3.100, toutes les adresses de …native-form-handler.php?to=…, en minuscules |
| Caractères | uniquement des adresses sans risque (254 caractères au plus, sans guillemets, antislash, $, espaces) ; elles figurent comme chaînes PHP simples |
| Qui vérifie | mailer.php et, à partir de la version 1.3.100, native-form-handler.php (native-form-handler.php) ; le gestionnaire autorise en plus sa propre adresse d'expédition de la configuration SMTP |
| Fichier absent | (exports plus anciens) toute adresse valide est acceptée. Exportez de nouveau la page et mettez-la en ligne pour que la liste s'applique |
| Plusieurs destinataires par formulaire | non prévu : une valeur avec virgule échoue au contrôle de l'adresse |
Pour plusieurs destinataires : configurez une redirection dans la boîte du destinataire, ou utilisez plusieurs formulaires avec une adresse chacun. Une page peut contenir des formulaires avec des destinataires différents ; tous figurent alors dans recipients.php.
config.php (assets/vn-shared)#
assets/vn-shared/config.php contient les identifiants de messagerie. Le programme ne la génère qu'à l'export, à partir des paramètres du profil du programme (pas dans le dossier du projet).
Syntaxe (d'après buildSmtpConfigPhp)
<?php
$smtp_host = "smtp.example.com";
$smtp_port = 587;
$smtp_encryption = "tls";
$smtp_username = "name@example.com";
$smtp_password = "…";
$smtp_from_email = "name@example.com";
$smtp_from_name = "Meine Firma";
$hmac_secret = "…";| Variable | Signification |
|---|---|
$smtp_host, $smtp_port | Serveur, port (587 par défaut) |
$smtp_encryption | tls (STARTTLS), ssl (SMTPS), sinon aucun |
$smtp_username, $smtp_password | Identification (obligatoire) |
$smtp_from_email, $smtp_from_name | Expéditeur des e-mails |
$hmac_secret | Clé secrète pour le captcha mathématique ; générée une fois, elle reste stable d'un enregistrement à l'autre |
Le fichier n'est écrit que si SMTP est configuré (ou dans l'aperçu). En mode aperçu, les e-mails vont vers un collecteur de courrier local (fichiers .eml), jamais vers le vrai serveur. Quand l'utilisateur enregistre à nouveau les paramètres SMTP, le programme met immédiatement à jour un publish/assets/vn-shared/config.php existant.
Paramètres SMTP dans le programme#
Paramètres › SMTP (envoi d’e-mails) : serveur, port, chiffrement, utilisateur, mot de passe, adresse et nom de l'expéditeur. Le programme vérifie avant l'enregistrement :
| Règle | Message (en substance) |
|---|---|
Serveur uniquement sous forme de nom, sans https:// et sans barres obliques | « Pour le serveur SMTP, indiquez uniquement le nom … » |
| Port 1–65535 (habituellement 587 ou 465) | « Le port doit être un nombre … » |
| Adresse d'expéditeur obligatoire si un serveur est saisi | « Veuillez saisir une adresse e-mail d'expéditeur » |
L'adresse d'expéditeur doit ressembler à name@example.com | « L'adresse e-mail de l'expéditeur n'est pas valide » |
Les identifiants se trouvent dans le profil du programme (stockage chiffré), jamais dans le projet. Le même config.php est lu par mailer.php, captcha.php et native-form-handler.php.
hCaptcha (Form Renderer uniquement)#
Un champ hcaptcha dans le formulaire charge le script https://js.hcaptcha.com/1/api.js de hCaptcha et vérifie la réponse côté serveur auprès de https://api.hcaptcha.com/siteverify. Le secret se trouve dans assets/vn-formrender/config.php ($hcaptcha_secret), généré à l'export à partir du profil du programme. La clé de site (site key) se trouve dans le JSON du formulaire (hcaptchaSiteKey sur le champ).
native-form-handler.php#
Pour les formulaires classiques sans JavaScript (un vrai <form method="post">), l'export fournit assets/vn-formrender/native-form-handler.php (avec tous les fichiers du dossier, dès qu'un bloc de formulaire figure sur une page).
| Caractéristique | Comportement |
|---|---|
| Appel | native-form-handler.php?to=name@example.com comme action |
| Destinataire | to de l'adresse ; s'il manque ou n'est pas une adresse valide, l'e-mail part à l'adresse d'expédition de la configuration SMTP. À partir de la version 1.3.100, le gestionnaire n'envoie qu'aux adresses de recipients.php et à sa propre adresse d'expédition (Destinataires) |
| Champs | tous les champs POST sauf website, captcha_*, copy_to_sender, vnmailer_*, h-captcha-response ; nom du champ = libellé ; valeurs sans HTML, 2000 caractères au plus |
| Reply-To | champ dont le nom ressemble à email, e-mail, email1 |
| Champs de contrôle | vnmailer_id, vnmailer_subject, vnmailer_copy_subject, vnmailer_copy_intro, vnmailer_hcaptcha_sitekey, captcha_answer, captcha_token, copy_to_sender, website (pot de miel) |
| Réponse | AJAX (X-Requested-With ou Accept: application/json) : JSON ; sinon redirection vers la page (Referer) avec vnmailer=success|error, vnmailer_msg, vnmailer_id |
| Limitation par IP | 15 requêtes par 10 minutes |
Liste de destinataires (à partir de la version 1.3.100). Le gestionnaire compare le destinataire (to, sans tenir compte de la casse) avec la liste de assets/vn-formrender/recipients.php. Sont autorisées les adresses de cette liste et toujours sa propre adresse d'expédition de la configuration SMTP ; toute autre adresse reçoit la réponse Dieser Empfänger ist für das Formular nicht freigegeben. Le contenu de la liste est écrit par l'export : il rassemble les adresses de data-recipient et de …native-form-handler.php?to=… dans le HTML de toutes les pages exportées (l'adresse peut être encodée en URL) et crée recipients.php même si une page utilise le gestionnaire sans to (la liste est alors vide, seule l'adresse d'expédition s'applique).
Comportement de l'export#
Si l'export trouve class="vn-formrender" ou class="vn-sform-form" dans une page quelconque, voici ce qui se passe :
| Résultat | Chemin |
|---|---|
| Fichiers d'envoi | assets/vn-formrender/ (répertoire complet issu de vendor/vn-formrender : mailer.php, captcha.php, native-form-handler.php, render.js, PHPMailer) |
| JSON des formulaires | assets/vn-formrender/forms/*.json, plus forms/.htaccess avec Options -Indexes |
| Liste des destinataires | assets/vn-formrender/recipients.php (si des adresses ont été trouvées ou si une page utilise native-form-handler.php) |
| Secret hCaptcha | assets/vn-formrender/config.php (si configuré) |
| Identifiants | assets/vn-shared/config.php (si SMTP configuré) |
Script (uniquement vn-sform) | vendor/vn-sform/vn-sform.js, inclus en fin de page |
Si SMTP n'est pas configuré, l'export affiche un avertissement ; le formulaire répond alors Formular ist noch nicht konfiguriert.
Formulaires avec VN Form Editor et le Form Renderer#
Fonctionnement d'ensemble#
- Dans VN Form Editor (outil, fenêtre avec palette, canevas, propriétés, onglets « Règles » et « Aperçu »), vous construisez le formulaire par glisser-déposer.
- Il est enregistré dans le projet sous
assets/vn-formrender/forms/<name>.json. - Un bloc Form Renderer (cinq designs) porte le nom dans le champ de panneau
formFile; un script charge à l'exécutionrender.js, qui récupère le JSON (fetch), construit le formulaire, évalue les règles et envoie viamailer.php.
Le JSON du formulaire#
Syntaxe
{
"fields": [
{ "id": "f1", "type": "text", "label": "Name", "placeholder": "", "value": "", "required": true,
"hiddenByDefault": false, "options": [], "linkText": "", "linkUrl": "", "width": 50 }
],
"rules": [
{ "id": "r1", "target": "f2", "action": "show", "value": "", "logic": "AND",
"conditions": [ { "field": "f1", "op": "equals", "value": "Ja" } ] }
]
}| Élément | Règle |
|---|---|
| Emplacement | assets/vn-formrender/forms/<name>.json |
| Nom | ^[a-zA-Z0-9_-]{1,60}$ (le programme et le renderer éliminent tout le reste) |
| Contenu minimal | un tableau fields ; si rules manque, [] s'applique |
| Ce qui est enregistré | { fields, rules }, indenté, de façon atomique (fichier temporaire, puis renommage) |
Propriétés des champs#
| Propriété | Type | Signification |
|---|---|---|
id | Texte (f1, f2 …) | Identifiant unique ; la cible et les conditions des règles y font référence |
type | Texte | voir le tableau suivant |
label | Texte | Libellé (titre pour heading, texte pour submit) |
placeholder | Texte | Texte indicatif pour les champs de texte et multilignes |
value | Texte | Valeur pour hidden |
required | Interrupteur | Champ obligatoire (consent est toujours obligatoire) |
hiddenByDefault | Interrupteur | Le champ démarre invisible (seules les règles peuvent l'afficher) |
options | Liste | Entrées pour select, radio (par défaut ["Option 1","Option 2"]) |
width | Pourcentage | Largeur (calc(<w>% - var(--vfr-gap))) ; 100 par défaut ; heading, hcaptcha toujours à 100 % |
linkText, linkUrl, linkSuffix | Texte | pour consent : texte, adresse, suite de phrase (« gelesen und akzeptiere sie. ») |
hcaptchaSiteKey | Texte | pour hcaptcha |
linkDisplayText, linkDisplayUrl | Texte | pour linkdisplay |
Types de champs#
type | Description |
|---|---|
text, email, tel, url, number, date | Saisie sur une ligne (input[type=…]) ; email sert en plus de Reply-To |
textarea | Texte multiligne (compteur de caractères facultatif) |
select | Liste de choix à partir de options |
radio | Groupe d'options à partir de options |
checkbox | Case à cocher simple |
file | Envoi de fichier (taille maxFileSizeMB), joint comme pièce jointe |
hidden | Champ caché avec value |
heading | Titre ; en mode « plusieurs pages », il commence une nouvelle page |
consent | Case de protection des données avec lien (linkText, linkUrl, linkSuffix), toujours obligatoire |
copytosender | « Me mettre en copie » (case à cocher, agit comme copy_to_sender) |
captcha | Question de sécurité mathématique (comme pour vn-sform) |
hcaptcha | hCaptcha (voir hCaptcha) |
signature | Signature (zone de dessin), envoyée comme image (PNG) |
linkdisplay | Simple affichage de lien (sans valeur) |
submit | Bouton d'envoi |
Règles#
Une règle observe des champs et agit sur un champ cible. Chaque modification dans le formulaire réévalue toutes les règles (engineApply) : d'abord l'état de base est rétabli (hiddenByDefault, required), puis s'appliquent les règles dont la condition est remplie.
Syntaxe
{ "id": "r1", "target": "f3", "action": "show", "value": "", "logic": "AND",
"conditions": [
{ "field": "f1", "op": "equals", "value": "Ja" },
{ "logic": "OR", "conditions": [
{ "field": "f2", "op": "greaterThan", "value": "10" },
{ "field": "f4", "op": "checked" }
] }
] }| Propriété | Valeurs | Signification |
|---|---|---|
target | id du champ | Champ cible (inutile pour redirect) |
action | voir Actions | Ce qui se produit |
value | Texte | Valeur pour setValue, adresse pour redirect |
logic | AND (toutes), OR (une) | Combinaison des conditions de ce niveau |
conditions | Liste | Entrées { field, op, value } ou groupes imbriqués { logic, conditions } |
carryValues | Interrupteur, activé par défaut | Pour redirect : ajoute toutes les valeurs saisies comme paramètres d'adresse |
Opérateurs#
op | Vérifie | Valeur requise |
|---|---|---|
equals / notEquals | texte égal / différent (exact) | oui |
contains / notContains | contient / ne contient pas (casse ignorée) | oui |
isEmpty / isNotEmpty | vide / non vide | non |
greaterThan / lessThan | comparaison numérique | oui |
checked / notChecked | case cochée / non cochée | non |
Radio et liste de choix comparent le texte exact de l'option. Une case à cocher ne mémorise que activé/désactivé : utilisez checked, pas equals "ja". Les sources de conditions sont les champs ayant une vraie valeur (text, textarea, email, tel, url, number, select, radio, checkbox, date, file, hidden, copytosender).
Actions#
action | Effet |
|---|---|
show | Afficher le champ cible |
hide | Masquer le champ cible |
require | Rendre le champ cible obligatoire |
unrequire | Supprimer l'obligation |
enable | Activer le champ cible |
disable | Désactiver le champ cible |
setValue | Définir la valeur (déclenche change) |
redirect | Rediriger vers l'adresse de value (une seule fois ; valeurs comme paramètres si carryValues) |
Le bloc Form Renderer#
Le bloc (vn-formrender, cinq designs : Standard, Arrière-plan, Cadre d'image, Carte photo, Overlay) contient un élément de données masqué, une zone de sortie, un aperçu pour l'éditeur et un petit script de démarrage.
Syntaxe (squelette du bloc « Standard »)
<section class="vn-formrender" group="Form" id="{{vn-id}}">
<vn-parameters> … </vn-parameters>
<div class="vnfr-data" data-formfile="{{formFile}}" data-recipient="{{recipientEmail}}"
data-subject="{{emailSubject}}" data-style="standard" style="display:none;"></div>
<div class="container">
<div class="vnfr-builder-dummy"> … Vorschau (nur im Editor) … </div>
<div class="vnfr-out"></div>
</div>
<script> … setzt data-vnfr-pending und lädt assets/vn-formrender/render.js … </script>
</section>| Élément | Signification |
|---|---|
section.vn-formrender | Reconnaissance à l'export (copie vn-formrender/, écrit recipients.php) |
.vnfr-data[data-…] | Réglages pour render.js (tableau ci-dessous) |
.vnfr-out | C'est ici que render.js construit le formulaire |
.vnfr-builder-dummy | Aperçu statique ; visible dans l'éditeur (#canvas .vn-formrender .vnfr-builder-dummy {display:block}), remplacé sur la page par render.js |
data-vnfr-pending | Le script de démarrage marque la section avant de placer render.js dans le <head> ; render.js cherche la section en attente |
data-vnfr-rendered | Posé par render.js après la construction |
Le script de démarrage détecte l'éditeur avec document.documentElement.classList.contains('is-builder'). Le programme ne pose jamais cette classe (voir Détection de l'éditeur) ; dans l'éditeur, c'est donc la branche « live » du script de démarrage qui s'exécute. L'aperçu de l'éditeur (.vnfr-builder-dummy) reste visible grâce à une règle du CSS du canevas.
Réglages sur .vnfr-data (noms en minuscules ; valeurs booléennes true/on/1 ; une valeur contenant encore {{ compte comme vide) :
| Attribut | Défaut | Signification |
|---|---|---|
data-formfile | — | Nom du JSON (sans chemin ni extension ; uniquement [a-zA-Z0-9_-]) |
data-recipient | — | Destinataire |
data-subject | Neue Nachricht über die Webseite | Objet |
data-copytosender | désactivé | Copie à l'expéditeur par défaut |
data-thankyouurl | vide | Page de remerciement |
data-style | standard | Design |
data-cardwidth, data-cardopacity, data-cardbg | 45, 100, #ffffff | Carte (Carte photo/Overlay) |
data-overlaybtn | Kontakt aufnehmen | Texte du bouton du design Overlay |
data-inputstyle | boxed | boxed ou underline |
data-inputbg, data-inputbgopacity | #ffffff, 100 | Arrière-plan des champs |
data-customfont | vide | Nom d'une police Google ; charge la police depuis fonts.googleapis.com |
data-twocolumns | désactivé | Mise en page automatique à 2 colonnes |
data-mobilekeepwidth | désactivé | Conserver la largeur propre des champs sur mobile |
data-borderless, data-stickyform, data-compactmode, data-syncradius | désactivé | Sans bordure, fixe, compact, rayons couplés |
data-shadowlevel | soft | none, soft, medium, strong |
data-showfieldicons | désactivé | Icônes devant les libellés |
data-maxfilesizemb | 3 | Limite de fichier dans le navigateur (Mo ; 1–8 dans le panneau) |
data-captchatransparent | désactivé | Boîte du captcha sans arrière-plan |
data-livevalidation | désactivé | Validation en direct avec coche |
data-charcounter | désactivé | Compteur de caractères pour textarea |
data-showprogressbar | désactivé | Barre de progression avec plusieurs titres |
data-multistep, data-multistepnexttext, data-multistepbacktext | désactivé, Weiter, Zurück | Plusieurs pages (titres = pages) |
data-hcaptchasize, data-hcaptchatheme | normal, light | normal/compact ; light/dark |
data-submiticon | none | arrow, check, paperplane |
data-successanimation | désactivé | Animation de réussite |
data-backgroundfullblock | désactivé | Arrière-plan sur tout le bloc (classe vnfr-background-fullblock) |
Enregistrer et intégrer#
| Étape | Emplacement |
|---|---|
| Enregistrer | Dans Form Editor : champ de nom, « Enregistrer » ; liste des formulaires enregistrés pour ouvrir, nouveau, supprimer ; indicateur « Ungespeichert » (non enregistré) |
| Échange | Import et téléchargement de JSON (pour l'emporter dans un autre projet) |
| Intégrer | Insérer le bloc « VN Form Renderer » ; dans le panneau, sous « Formular-Konfiguration » (configuration du formulaire), saisir le nom de fichier (le champ propose les noms enregistrés sous forme de liste, saisie libre possible) |
| Destinataire | Champ de panneau recipientEmail ; objet emailSubject ; page de remerciement thankYouUrl |
| Statique au lieu de dynamique | Bloc « Formulaire (statique) » dans l'onglet « Code personnalisé » (voir sform-from-editor) |
À l'export, il suffit de placer le bloc sur une page : le programme emporte forms/<name>.json et génère recipients.php.
Remarques de sécurité#
| Sujet | Mesure |
|---|---|
| Sortie | mailer.php échappe toutes les valeurs (htmlspecialchars), les sauts de ligne dans l'objet sont supprimés |
| Destinataire | Uniquement les adresses de recipients.php (mailer.php ; native-form-handler.php de même à partir de la version 1.3.100, avec en plus sa propre adresse d'expédition) ; une adresse par formulaire |
| Spam | Pot de miel, limitation par IP (5 par 10 minutes), captcha mathématique facultatif (jeton signé) ou hCaptcha |
| Taille | 40 champs, 8000 caractères, 8/15 Mo de pièces jointes |
| Identifiants | config.php avec le mot de passe SMTP à servir uniquement via PHP ; mot de passe jamais dans le dossier du projet |
| Envoi de fichiers | ne sont pas enregistrés, seulement joints ; le fournisseur de messagerie contrôle les pièces jointes |
| Champs obligatoires | contrôlés uniquement dans le navigateur, pas côté serveur |
| Relais ouvert | à partir de la version 1.3.100, native-form-handler.php vérifie par rapport à recipients.php ; sans ce fichier (export avec une version plus ancienne), il envoie à n'importe quelle adresse. Réexporter et remettre en ligne les anciennes pages |
| Tiers | data-customfont (Google Fonts) et hCaptcha se chargent sans consentement |