Documentation développeur VN-Designer
08

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.

VoieEmplacement du formulaireQuand 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 navigateurFormulaires 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

html
<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émentObligatoireRôle
form.vn-sform-formouiMarqueur 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 champUn champ avec son libellé ; data-type détermine l'évaluation
.vn-sform-labelouiLibellé ; son texte devient le nom du champ dans l'e-mail
div.vn-sform-hp avec input[name="website"]ouiPot de miel (honeypot, piège à spam), voir Protection anti-spam
button.vn-sform-enterrecommandéBouton d'envoi invisible, pour que Entrée dans un champ envoie le formulaire
div.vn-sform-statusouiZone de message (hidden), voir Messages
a[data-vn-sform-submit]ouiLe bouton d'envoi
novalidateouiLa validation est assurée par le script (messages d'erreur propres sous les champs)

L'élément form : attributs data#

AttributType/valeursDéfautSignification
data-recipientadresse e-mail—Destinataire ; exactement une adresse (voir Destinataires)
data-subjecttexteNeue Nachricht über die WebseiteObjet de l'e-mail (150 caractères au plus, sauts de ligne supprimés)
data-successtexteDanke für deine Nachricht! (avec lang="en" : Thank you for your message!)Message après un envoi réussi
data-thankyouadressevidePage de remerciement : si elle est définie, le visiteur y est redirigé au lieu de voir le message
data-mailercheminassets/vn-formrender/mailer.phpAdresse du script d'envoi, relative à la page ; captcha.php en est déduit (mailer.php… → captcha.php)
data-vn-sform-ready1—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 saisieValeur dans l'e-mail
text, tel, url, number, dateinput.vn-sform-input[type=…]texte saisi (sans espaces superflus)
emailinput[type=email]texte ; la première adresse e-mail valide devient Reply-To et destinataire de la copie à l'expéditeur
textareatextarea.vn-sform-input.vn-sform-textareatexte
selectselect.vn-sform-input.vn-sform-selectvalue choisie
radiodiv.vn-sform-choices avec plusieurs input[type=radio] (même name)value choisie ; obligatoire si le premier bouton radio porte required
checkboxinput[type=checkbox]Ja ou Nein
consentinput[type=checkbox][required] (protection des données)Ja/Nein ; toujours obligatoire
copytosenderinput[type=checkbox][data-vn-copytosender]absent de l'e-mail ; active la copie à l'expéditeur
fileinput.vn-sform-file[type=file]fichier en pièce jointe ; nom et taille dans l'e-mail
captchavoir Question de sécuritéabsent de l'e-mail
headingh3.vn-sform-heading (le champ s'appelle vn-sform-field vn-sform-heading-wrap)ignoré
submita.btn.vn-sform-submit[data-vn-sform-submit]ignoré
(sans champ) input[type=hidden]name, value, data-labelentrée sous data-label (sinon name), si une valeur est présente

Exemples (d'après src/vn-sform.js) :

html

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

IndicationValeurSignification
style="--span:N"1–12Nombre de colonnes ; 6 = demi-largeur, 12 = ligne entière
depuis l'éditeur de formulaireswidth 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 videBitte ausfüllen.
Champ e-mail avec adresse invalideBitte eine gültige E-Mail-Adresse eingeben.
Case obligatoire non cochéeBitte bestätigen.
Groupe radio sans choix (premier radio required)Bitte auswählen.
Fichier obligatoire manquantBitte eine Datei wählen.
Fichier de plus de 3 MoDie Datei ist zu groß (max. 3 MB).
Champ de calcul videBitte 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

html
<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>
AttributSignification
data-vn-sform-submitUn clic envoie le formulaire (preventDefault) ; le script pose alors vn-sform-busy sur le bouton (pas de double clic)
a.btnLe bouton est un bouton normal, modifiable d'un clic (couleur, libellé, icône ; voir Boutons)
.vn-sform-enterbutton[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).

ProtectionOùDescription
Pot de miel (honeypot) websiteFormulaire + serveurNon vide = faux succès silencieux
Question de sécurité mathématiqueType de champ captchaUniquement si le formulaire contient le champ
Limitation par IPServeur5 requêtes par 10 minutes au plus par adresse de visiteur (réponse Zu viele Anfragen, bitte später erneut versuchen.)
Limitation de tailleServeur40 champs au plus, 8000 caractères au total (noms + valeurs)
Liste des destinatairesServeuruniquement les adresses de recipients.php (Destinataires)

Question de sécurité mathématique#

Syntaxe

html
<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>
AttributSignification
data-vn-captcha-qLe script y écrit l'opération (a + b = ?, nombres de 1 à 9)
data-vn-captcha-answerLe champ de réponse
data-vn-captcha-tokenChamp 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#

CasAffichage
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éseauDas 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.

LimiteValeurOù
Taille par fichier dans le navigateur3 Movn-sform.js (message au moment du choix)
Taille par fichier sur le serveur8 Momailer.php (Datei zu groß (max. 8 MB).)
Toutes les pièces jointes ensemble15 Momailer.php
Typesaucune restrictionLe 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) :

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)TypeSignification
recipientTexteDestinataire (vers data-recipient)
subjectTexteObjet (data-subject)
successTextTexteMessage de réussite (data-success)
thankYouUrlTextePage de remerciement (data-thankyou)
padding, maxWidth, align, gapNombres/choixMarge, largeur maximale, alignement, espacement des champs
fieldStyleoutline, filled, lineApparence des champs
radius, fieldSizeNombre, sm/md/lgArrondi, taille
borderColor, fieldBg, focusColorCouleurBordure, arrière-plan, focus
bgColor, labelColor, textColor, errorColor, okColorCouleurCouleurs de fond et de texte
btnAlignleft, center, right, fullAlignement 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) :

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

GroupeTypes de champs
Repristext, 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 &#123;&#123; 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 }.

ÉtapeContrôleRéponse en cas d'infraction
1La méthode doit être POSTUngültige Anfrage-Methode.
2../vn-shared/config.php doit exister et contenir $hmac_secret, $smtp_host, $smtp_username, $smtp_passwordFormular ist noch nicht konfiguriert …
3Lecture du contenu (JSON ou multipart)Ungültige Anfrage.
4Pot de miel website non videLe succès est simulé, rien n'est envoyé
5hCaptcha ou captcha mathématique (selon ce qui a été envoyé)Sicherheitsabfrage … / hCaptcha-Prüfung fehlgeschlagen …
6Limitation par IP : 5 requêtes par 10 minutes (fichier dans sys_get_temp_dir())Zu viele Anfragen, bitte später erneut versuchen.
7recipient doit être une seule adresse e-mail valideKein gültiger Empfänger konfiguriert.
8L'adresse doit figurer dans recipients.php (si le fichier existe)Dieser Empfänger ist für das Formular nicht freigegeben.
9Il doit y avoir des champs ou des fichiers ; 40 champs et 8000 caractères au plusKeine Formulardaten übermittelt. / Eingabe zu lang.
10Fichiers : 8 Mo par fichier, 15 Mo au total, uniquement de vrais envoisDatei zu groß … / Anhänge zusammen zu groß …
11Objet : 150 caractères au plus, \r/\n supprimés (injection d'en-têtes)—
12E-mail : tableau HTML (nom du champ, valeur ; valeurs avec htmlspecialchars et nl2br) et version texte ; Reply-To seulement avec une adresse valideMail konnte nicht versendet werden, bitte später erneut versuchen.
13Copie facultative à l'expéditeurLes 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
<?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ègleDescription
Contenutoutes 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èresuniquement des adresses sans risque (254 caractères au plus, sans guillemets, antislash, $, espaces) ; elles figurent comme chaînes PHP simples
Qui vérifiemailer.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 formulairenon 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
<?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 = "…";
VariableSignification
$smtp_host, $smtp_portServeur, port (587 par défaut)
$smtp_encryptiontls (STARTTLS), ssl (SMTPS), sinon aucun
$smtp_username, $smtp_passwordIdentification (obligatoire)
$smtp_from_email, $smtp_from_nameExpéditeur des e-mails
$hmac_secretClé 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ègleMessage (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éristiqueComportement
Appelnative-form-handler.php?to=name@example.com comme action
Destinataireto 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)
Champstous 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-Tochamp dont le nom ressemble à email, e-mail, email1
Champs de contrôlevnmailer_id, vnmailer_subject, vnmailer_copy_subject, vnmailer_copy_intro, vnmailer_hcaptcha_sitekey, captcha_answer, captcha_token, copy_to_sender, website (pot de miel)
RéponseAJAX (X-Requested-With ou Accept: application/json) : JSON ; sinon redirection vers la page (Referer) avec vnmailer=success|error, vnmailer_msg, vnmailer_id
Limitation par IP15 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ésultatChemin
Fichiers d'envoiassets/vn-formrender/ (répertoire complet issu de vendor/vn-formrender : mailer.php, captcha.php, native-form-handler.php, render.js, PHPMailer)
JSON des formulairesassets/vn-formrender/forms/*.json, plus forms/.htaccess avec Options -Indexes
Liste des destinatairesassets/vn-formrender/recipients.php (si des adresses ont été trouvées ou si une page utilise native-form-handler.php)
Secret hCaptchaassets/vn-formrender/config.php (si configuré)
Identifiantsassets/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#

  1. 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.
  2. Il est enregistré dans le projet sous assets/vn-formrender/forms/<name>.json.
  3. Un bloc Form Renderer (cinq designs) porte le nom dans le champ de panneau formFile ; un script charge à l'exécution render.js, qui récupère le JSON (fetch), construit le formulaire, évalue les règles et envoie via mailer.php.

Le JSON du formulaire#

Syntaxe

json
{
  "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émentRègle
Emplacementassets/vn-formrender/forms/<name>.json
Nom^[a-zA-Z0-9_-]{1,60}$ (le programme et le renderer éliminent tout le reste)
Contenu minimalun 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éTypeSignification
idTexte (f1, f2 …)Identifiant unique ; la cible et les conditions des règles y font référence
typeTextevoir le tableau suivant
labelTexteLibellé (titre pour heading, texte pour submit)
placeholderTexteTexte indicatif pour les champs de texte et multilignes
valueTexteValeur pour hidden
requiredInterrupteurChamp obligatoire (consent est toujours obligatoire)
hiddenByDefaultInterrupteurLe champ démarre invisible (seules les règles peuvent l'afficher)
optionsListeEntrées pour select, radio (par défaut ["Option 1","Option 2"])
widthPourcentageLargeur (calc(<w>% - var(--vfr-gap))) ; 100 par défaut ; heading, hcaptcha toujours à 100 %
linkText, linkUrl, linkSuffixTextepour consent : texte, adresse, suite de phrase (« gelesen und akzeptiere sie. »)
hcaptchaSiteKeyTextepour hcaptcha
linkDisplayText, linkDisplayUrlTextepour linkdisplay

Types de champs#

typeDescription
text, email, tel, url, number, dateSaisie sur une ligne (input[type=…]) ; email sert en plus de Reply-To
textareaTexte multiligne (compteur de caractères facultatif)
selectListe de choix à partir de options
radioGroupe d'options à partir de options
checkboxCase à cocher simple
fileEnvoi de fichier (taille maxFileSizeMB), joint comme pièce jointe
hiddenChamp caché avec value
headingTitre ; en mode « plusieurs pages », il commence une nouvelle page
consentCase de protection des données avec lien (linkText, linkUrl, linkSuffix), toujours obligatoire
copytosender« Me mettre en copie » (case à cocher, agit comme copy_to_sender)
captchaQuestion de sécurité mathématique (comme pour vn-sform)
hcaptchahCaptcha (voir hCaptcha)
signatureSignature (zone de dessin), envoyée comme image (PNG)
linkdisplaySimple affichage de lien (sans valeur)
submitBouton 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

json
{ "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éValeursSignification
targetid du champChamp cible (inutile pour redirect)
actionvoir ActionsCe qui se produit
valueTexteValeur pour setValue, adresse pour redirect
logicAND (toutes), OR (une)Combinaison des conditions de ce niveau
conditionsListeEntrées { field, op, value } ou groupes imbriqués { logic, conditions }
carryValuesInterrupteur, activé par défautPour redirect : ajoute toutes les valeurs saisies comme paramètres d'adresse

Opérateurs#

opVérifieValeur requise
equals / notEqualstexte égal / différent (exact)oui
contains / notContainscontient / ne contient pas (casse ignorée)oui
isEmpty / isNotEmptyvide / non videnon
greaterThan / lessThancomparaison numériqueoui
checked / notCheckedcase cochée / non cochéenon

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#

actionEffet
showAfficher le champ cible
hideMasquer le champ cible
requireRendre le champ cible obligatoire
unrequireSupprimer l'obligation
enableActiver le champ cible
disableDésactiver le champ cible
setValueDéfinir la valeur (déclenche change)
redirectRediriger 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 »)

html
<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émentSignification
section.vn-formrenderReconnaissance à l'export (copie vn-formrender/, écrit recipients.php)
.vnfr-data[data-…]Réglages pour render.js (tableau ci-dessous)
.vnfr-outC'est ici que render.js construit le formulaire
.vnfr-builder-dummyAperçu statique ; visible dans l'éditeur (#canvas .vn-formrender .vnfr-builder-dummy {display:block}), remplacé sur la page par render.js
data-vnfr-pendingLe script de démarrage marque la section avant de placer render.js dans le <head> ; render.js cherche la section en attente
data-vnfr-renderedPosé 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) :

AttributDéfautSignification
data-formfile—Nom du JSON (sans chemin ni extension ; uniquement [a-zA-Z0-9_-])
data-recipient—Destinataire
data-subjectNeue Nachricht über die WebseiteObjet
data-copytosenderdésactivéCopie à l'expéditeur par défaut
data-thankyouurlvidePage de remerciement
data-stylestandardDesign
data-cardwidth, data-cardopacity, data-cardbg45, 100, #ffffffCarte (Carte photo/Overlay)
data-overlaybtnKontakt aufnehmenTexte du bouton du design Overlay
data-inputstyleboxedboxed ou underline
data-inputbg, data-inputbgopacity#ffffff, 100Arrière-plan des champs
data-customfontvideNom d'une police Google ; charge la police depuis fonts.googleapis.com
data-twocolumnsdésactivéMise en page automatique à 2 colonnes
data-mobilekeepwidthdésactivéConserver la largeur propre des champs sur mobile
data-borderless, data-stickyform, data-compactmode, data-syncradiusdésactivéSans bordure, fixe, compact, rayons couplés
data-shadowlevelsoftnone, soft, medium, strong
data-showfieldiconsdésactivéIcônes devant les libellés
data-maxfilesizemb3Limite de fichier dans le navigateur (Mo ; 1–8 dans le panneau)
data-captchatransparentdésactivéBoîte du captcha sans arrière-plan
data-livevalidationdésactivéValidation en direct avec coche
data-charcounterdésactivéCompteur de caractères pour textarea
data-showprogressbardésactivéBarre de progression avec plusieurs titres
data-multistep, data-multistepnexttext, data-multistepbacktextdésactivé, Weiter, ZurückPlusieurs pages (titres = pages)
data-hcaptchasize, data-hcaptchathemenormal, lightnormal/compact ; light/dark
data-submiticonnonearrow, check, paperplane
data-successanimationdésactivéAnimation de réussite
data-backgroundfullblockdésactivéArrière-plan sur tout le bloc (classe vnfr-background-fullblock)

Enregistrer et intégrer#

ÉtapeEmplacement
EnregistrerDans Form Editor : champ de nom, « Enregistrer » ; liste des formulaires enregistrés pour ouvrir, nouveau, supprimer ; indicateur « Ungespeichert » (non enregistré)
ÉchangeImport et téléchargement de JSON (pour l'emporter dans un autre projet)
IntégrerInsé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)
DestinataireChamp de panneau recipientEmail ; objet emailSubject ; page de remerciement thankYouUrl
Statique au lieu de dynamiqueBloc « 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é#

SujetMesure
Sortiemailer.php échappe toutes les valeurs (htmlspecialchars), les sauts de ligne dans l'objet sont supprimés
DestinataireUniquement 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
SpamPot de miel, limitation par IP (5 par 10 minutes), captcha mathématique facultatif (jeton signé) ou hCaptcha
Taille40 champs, 8000 caractères, 8/15 Mo de pièces jointes
Identifiantsconfig.php avec le mot de passe SMTP à servir uniquement via PHP ; mot de passe jamais dans le dossier du projet
Envoi de fichiersne sont pas enregistrés, seulement joints ; le fournisseur de messagerie contrôle les pièces jointes
Champs obligatoirescontrô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
Tiersdata-customfont (Google Fonts) et hCaptcha se chargent sans consentement