Formulare
Das statische Formular (vn-sform) mit allen Markierungen, der gemeinsame PHP-Versand (mailer.php, config.php, recipients.php, SMTP), Spam-Schutz sowie der VN Form Editor mit dem Form Renderer (Feldtypen, Regeln, Speichern, Einbinden).
Überblick#
Es gibt zwei Wege zu einem funktionierenden Formular. Beide verschicken über dasselbe PHP (mailer.php), dessen Zugangsdaten das Programm beim Export erzeugt.
| Weg | Wo das Formular steht | Wann wählen |
|---|---|---|
Statisches Formular (vn-sform) | Fertiges HTML im Block (Felder direkt im Template) | Kontaktformulare in Themes und Blöcken; alle Texte per Klick änderbar; Aussehen über Panel und CSS |
Form Renderer (vn-formrender) | Eine JSON-Datei, die der VN Form Editor erzeugt; der Block baut das Formular erst im Browser | Formulare mit Regeln (Ein-/Ausblenden), mehreren Schritten, Unterschrift, hCaptcha |
Voraussetzungen: Die Website liegt auf einem Server mit PHP. Die Seiten selbst dürfen .html heißen, nur das PHP in assets/vn-formrender/ muss ausgeführt werden. Absendeadresse und Mailserver (SMTP) stellen Sie im Programm ein (siehe SMTP-Einstellungen).
Das statische Formular: vn-sform#
Grundgerüst#
Syntax
<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>(aus src/vn-sform.js; dieselbe Form verwenden themes/vn-handwerk-src/components/kontakt1 und gallery-content/vn-app-theme/src/components/signup1)
| Teil | Pflicht | Aufgabe |
|---|---|---|
form.vn-sform-form | ja | Erkennungsmerkmal. Nur ein <form> mit dieser Klasse wird vom Skript übernommen und vom Export erkannt (class="… vn-sform-form …") |
div.vn-sform-field[data-type] | ja, je Feld | Ein Feld samt Beschriftung; data-type bestimmt die Auswertung |
.vn-sform-label | ja | Beschriftung; ihr Text wird zum Namen des Felds in der Mail |
div.vn-sform-hp mit input[name="website"] | ja | Honeypot (Spam-Falle), siehe Spam-Schutz |
button.vn-sform-enter | empfohlen | Unsichtbarer Absende-Knopf, damit Enter im Feld absendet |
div.vn-sform-status | ja | Meldungsfläche (hidden), siehe Meldungen |
a[data-vn-sform-submit] | ja | Der Absenden-Knopf |
novalidate | ja | Die Prüfung übernimmt das Skript (eigene Fehlermeldungen unter den Feldern) |
Das form-Element: data-Attribute#
| Attribut | Typ/Werte | Standard | Bedeutung |
|---|---|---|---|
data-recipient | E-Mail-Adresse | — | Empfänger; genau eine Adresse (siehe Empfänger) |
data-subject | Text | Neue Nachricht über die Webseite | Betreff der Mail (höchstens 150 Zeichen, Zeilenumbrüche entfernt) |
data-success | Text | Danke für deine Nachricht! (bei lang="en": Thank you for your message!) | Meldung nach erfolgreichem Absenden |
data-thankyou | Adresse | leer | Danke-Seite: ist sie gesetzt, wird dorthin weitergeleitet statt die Meldung zu zeigen |
data-mailer | Pfad | assets/vn-formrender/mailer.php | Adresse des Versand-Skripts, relativ zur Seite; captcha.php wird daraus abgeleitet (mailer.php… → captcha.php) |
data-vn-sform-ready | 1 | — | Vom Skript gesetzt: Formular ist initialisiert (nicht von Hand setzen) |
Feldtypen#
Jedes Feld ist ein div.vn-sform-field mit data-type. Das Skript sammelt alle .vn-sform-field[data-type], liest dort die Beschriftung (.vn-sform-label) und das erste Eingabeelement (input:not([type=radio]), textarea, select).
data-type | Eingabeelement | Wert in der Mail |
|---|---|---|
text, tel, url, number, date | input.vn-sform-input[type=…] | eingegebener Text (getrimmt) |
email | input[type=email] | Text; die erste gültige E-Mail-Adresse wird Reply-To und Ziel der Absenderkopie |
textarea | textarea.vn-sform-input.vn-sform-textarea | Text |
select | select.vn-sform-input.vn-sform-select | gewählter value |
radio | div.vn-sform-choices mit mehreren input[type=radio] (gleicher name) | gewählter value; Pflicht, wenn der erste Radio required trägt |
checkbox | input[type=checkbox] | Ja oder Nein |
consent | input[type=checkbox][required] (Datenschutz) | Ja/Nein; immer Pflicht |
copytosender | input[type=checkbox][data-vn-copytosender] | nicht in der Mail; schaltet die Kopie an den Absender ein |
file | input.vn-sform-file[type=file] | Datei als Anhang; in der Mail Name und Größe |
captcha | siehe Sicherheitsabfrage | nicht in der Mail |
heading | h3.vn-sform-heading (Feld heißt vn-sform-field vn-sform-heading-wrap) | wird übersprungen |
submit | a.btn.vn-sform-submit[data-vn-sform-submit] | wird übersprungen |
(ohne Feld) input[type=hidden] | name, value, data-label | Eintrag unter data-label (sonst name), wenn ein Wert da ist |
Beispiele (aus 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>Raster: --span#
Das Feldraster hat 12 Spalten (.vn-sform-fields { display:grid; grid-template-columns: repeat(12, 1fr) }). Die Breite eines Felds steht als Stilvariable am Feld.
| Angabe | Wert | Bedeutung |
|---|---|---|
style="--span:N" | 1–12 | Spaltenzahl; 6 = halbe Breite, 12 = ganze Zeile |
| aus dem Formular-Editor | width in % | wird zu --span = round(width/100*12) (1–12; ungültig = 12) |
| Handy (unter 640 px) | — | jedes Feld wird 12 Spalten breit |
Themes mit Bootstrap-Raster (row g-3, col-sm-6) funktionieren ebenso: Das Skript liest nur .vn-sform-field[data-type], nicht die Spalten (Beispiel kontakt1 im VN-Handwerk-Theme).
Pflichtfelder#
Pflicht ist das Attribut required am Eingabeelement. Der Stern ist reine Optik (<span class="vn-sform-req" aria-hidden="true"> *</span> in der Beschriftung); das Skript entfernt ihn aus dem Feldnamen in der Mail.
| Prüfung (im Browser, vor dem Senden) | Meldung |
|---|---|
| Pflichtfeld leer | Bitte ausfüllen. |
| E-Mail-Feld mit ungültiger Adresse | Bitte eine gültige E-Mail-Adresse eingeben. |
| Pflicht-Checkbox nicht angehakt | Bitte bestätigen. |
Radiogruppe ohne Wahl (erster Radio required) | Bitte auswählen. |
| Pflicht-Datei fehlt | Bitte eine Datei wählen. |
| Datei größer als 3 MB | Die Datei ist zu groß (max. 3 MB). |
| Mathe-Feld leer | Bitte ausfüllen. |
Fehlerfelder bekommen die Klasse vn-sform-invalid; unter ihnen steht ein <p class="vn-sform-error">. Das erste fehlerhafte Feld erhält den Fokus. Die Meldungen der Tabelle stehen im Skript fest auf Deutsch; nur die Hinweise der Mathe-Sicherheitsabfrage und die Ersatz-Erfolgsmeldung folgen dem lang am <html> (en = Englisch). Eigene Texte für Erfolg und Weiterleitung setzen Sie über data-success und data-thankyou.
Absenden-Knopf#
Syntax
<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 | Bedeutung |
|---|---|
data-vn-sform-submit | Klick sendet das Formular (preventDefault); das Skript setzt dabei vn-sform-busy auf den Knopf (kein Doppel-Klick) |
a.btn | Der Knopf ist ein normaler, per Klick änderbarer Button (Farbe, Beschriftung, Symbol; siehe Buttons) |
.vn-sform-enter | Zusätzlicher unsichtbarer button[type=submit], damit Enter in einem Feld sendet |
Spam-Schutz: Honeypot#
Das Feld input[name="website"] im div.vn-sform-hp ist für Menschen unsichtbar (aus dem Bild geschoben, tabindex="-1"). Füllt ein Bot es aus, gibt mailer.php Erfolg vor, ohne etwas zu senden (Bots merken keinen Unterschied).
| Schutz | Wo | Beschreibung |
|---|---|---|
Honeypot website | Formular + Server | Nicht leer = stiller Scheinerfolg |
| Mathe-Sicherheitsabfrage | Feldtyp captcha | Nur wenn das Formular das Feld enthält |
| IP-Begrenzung | Server | höchstens 5 Anfragen je 10 Minuten je Besucheradresse (Antwort Zu viele Anfragen, bitte später erneut versuchen.) |
| Größenbegrenzung | Server | höchstens 40 Felder, zusammen 8000 Zeichen (Namen + Werte) |
| Empfängerliste | Server | nur Adressen aus recipients.php (Empfänger) |
Mathe-Sicherheitsabfrage#
Syntax
<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 | Bedeutung |
|---|---|
data-vn-captcha-q | Hier schreibt das Skript die Rechenaufgabe hinein (a + b = ?, Zahlen 1–9) |
data-vn-captcha-answer | Das Antwortfeld |
data-vn-captcha-token | Verstecktes Feld für das signierte Token |
Ablauf: Das Skript holt Frage und Token von captcha.php (?t=<Zeit>, kein Caching). Das Token ist base64({a,b,exp}) + "." + HMAC-SHA256, mit dem geheimen Schlüssel aus config.php (hmac_secret) signiert, 10 Minuten gültig; das Ergebnis steht nirgends im Klartext. mailer.php prüft Signatur, Ablauf und Summe. Nach jedem Absenden wird eine neue Aufgabe geladen. Ist captcha.php nicht erreichbar, steht in der Frage nicht verfügbar.
Meldungen und Weiterleitung#
| Fall | Anzeige |
|---|---|
Erfolg (HTTP 200, success: true) | Ohne data-thankyou: das Formular wird geleert, .vn-sform-status.vn-sform-ok zeigt data-success (sonst die Antwort des Servers, sonst Danke für deine Nachricht!). Mit data-thankyou: Weiterleitung dorthin |
| Fehler vom Server | .vn-sform-status.vn-sform-fail mit der Meldung des Servers (zum Beispiel Zu viele Anfragen …) |
| Netzwerkfehler | Das Formular konnte nicht gesendet werden. Bitte später erneut versuchen. |
Die Fläche .vn-sform-status ist standardmäßig hidden. Die Klassen vn-sform-ok und vn-sform-fail bestimmen Farbe und Rand.
Datei-Uploads#
Ein Feld data-type="file" schickt die Datei als Anhang der Mail. Sind Dateien gewählt, sendet das Skript multipart/form-data statt JSON.
| Grenze | Wert | Wo |
|---|---|---|
| Größe je Datei im Browser | 3 MB | vn-sform.js (Meldung beim Wählen) |
| Größe je Datei auf dem Server | 8 MB | mailer.php (Datei zu groß (max. 8 MB).) |
| Alle Anhänge zusammen | 15 MB | mailer.php |
| Typen | keine Einschränkung | Der Dateiname wird auf basename reduziert; die Datei wird nicht gespeichert, nur an die Mail gehängt |
Kopie an den Absender#
Das Feld data-type="copytosender" (Checkbox mit data-vn-copytosender) schaltet eine Kopie ein: Der Absender bekommt dieselbe Mail an die Reply-To-Adresse (die erste gültige E-Mail aus einem E-Mail-Feld), Betreff mit Zusatz „ (Kopie deiner Nachricht)“. Fehlschlag der Kopie meldet keinen Fehler.
Datenformat zum Server#
Das Skript sendet ohne Dateien JSON (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": "…" }
}Mit Dateien multipart/form-data mit den Feldern recipient, subject, reply_to, copy_to_sender (1 oder leer), website, captcha_answer, captcha_token, fields_json (JSON-Text derselben fields), files[], file_labels[]. Die Antwort ist immer JSON: { "success": true|false, "message": "…" } (HTTP 200 bei Erfolg, sonst 400/500).
Die Schlüssel in fields sind die Beschriftungen (ohne Stern). Gleiche Beschriftungen werden durch angehängte Leerzeichen unterscheidbar gehalten.
Eigenschaften-Panel des Bausteins#
Der fertige Baustein „Formular (statisch)“ bringt diese Felder mit (name in vn-parameters); sie sind nur dann nötig, wenn Sie einen eigenen Baustein mit Panel bauen:
Feld (name) | Art | Bedeutung |
|---|---|---|
recipient | Text | Empfänger (an data-recipient) |
subject | Text | Betreff (data-subject) |
successText | Text | Erfolgsmeldung (data-success) |
thankYouUrl | Text | Danke-Seite (data-thankyou) |
padding, maxWidth, align, gap | Zahlen/Auswahl | Abstand, Höchstbreite, Ausrichtung, Feldabstand |
fieldStyle | outline, filled, line | Aussehen der Felder |
radius, fieldSize | Zahl, sm/md/lg | Rundung, Größe |
borderColor, fieldBg, focusColor | Farbe | Rahmen, Hintergrund, Fokus |
bgColor, labelColor, textColor, errorColor, okColor | Farbe | Flächen- und Textfarben |
btnAlign | left, center, right, full | Ausrichtung des Absenden-Knopfs |
Beispiel: Kontaktformular im Theme#
Aus themes/vn-handwerk-src/components/kontakt1/template.html (verkürzt). Es nutzt Bootstrap-Klassen für das Raster und verbirgt die Beschriftungen optisch (visually-hidden), zeigt aber Platzhalter:
<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>Statisches Formular aus dem Formular-Editor#
Der Baustein „Formular (statisch)“ (createSformBlockEntry) übernimmt die Felder eines im VN Form Editor gebauten Formulars als fertiges HTML.
| Gruppe | Feldtypen |
|---|---|
| Übernommen | text, textarea, email, tel, url, number, date, select, radio, checkbox, file, hidden, heading, submit, consent, copytosender, captcha |
| Nicht übernommen (nur im Form Renderer) | hcaptcha, signature (Unterschrift), linkdisplay (Link-Anzeige), Regeln, mehrstufige Formulare |
Ohne Absenden-Feld ergänzt der Baustein einen Knopf „Absenden“. Feldnummern (f1, f2 …) werden fortlaufend neu vergeben; {{ im Feldtext wird als {{ geschrieben, damit der Text nie als Platzhalter gewertet wird.
Serverseite#
mailer.php#
Das gemeinsame Versand-Skript assets/vn-formrender/mailer.php (PHPMailer, SMTP). Antwort stets JSON { success, message }.
| Schritt | Prüfung | Antwort bei Verstoß |
|---|---|---|
| 1 | Methode muss POST sein | Ungültige Anfrage-Methode. |
| 2 | ../vn-shared/config.php muss existieren und $hmac_secret, $smtp_host, $smtp_username, $smtp_password enthalten | Formular ist noch nicht konfiguriert … |
| 3 | Inhalt lesen (JSON oder multipart) | Ungültige Anfrage. |
| 4 | Honeypot website nicht leer | Erfolg wird vorgetäuscht, es wird nichts gesendet |
| 5 | hCaptcha oder Mathe-Captcha (je nachdem, was mitgeschickt wurde) | Sicherheitsabfrage … / hCaptcha-Prüfung fehlgeschlagen … |
| 6 | IP-Begrenzung: 5 Anfragen je 10 Minuten (Datei in sys_get_temp_dir()) | Zu viele Anfragen, bitte später erneut versuchen. |
| 7 | recipient muss eine gültige einzelne E-Mail-Adresse sein | Kein gültiger Empfänger konfiguriert. |
| 8 | Adresse muss in recipients.php stehen (falls die Datei existiert) | Dieser Empfänger ist für das Formular nicht freigegeben. |
| 9 | Es muss Felder oder Dateien geben; höchstens 40 Felder, 8000 Zeichen | Keine Formulardaten übermittelt. / Eingabe zu lang. |
| 10 | Dateien: 8 MB je Datei, 15 MB gesamt, nur echte Uploads | Datei zu groß … / Anhänge zusammen zu groß … |
| 11 | Betreff: höchstens 150 Zeichen, \r/\n entfernt (Header-Injection) | — |
| 12 | Mail: HTML-Tabelle (Feldname, Wert; Werte mit htmlspecialchars und nl2br) und Textfassung; Reply-To nur bei gültiger Adresse | Mail konnte nicht versendet werden, bitte später erneut versuchen. |
| 13 | Optional Kopie an den Absender | Fehler der Kopie werden ignoriert |
Leere Felder werden nicht in die Mail aufgenommen. Fatale PHP-Fehler fängt ein Shutdown-Handler und liefert JSON statt einer leeren 500-Seite (mit Feld debug und Fundstelle).
Geprüft (PHP 8.3, eigener Testserver, SMTP absichtlich nicht erreichbar): mehrere Adressen durch Komma → Kein gültiger Empfänger konfiguriert.; fremde Adresse bei vorhandener recipients.php → nicht freigegeben; Honeypot → 200 mit Scheinerfolg; falscher Captcha-Token → Sicherheitsabfrage ungültig …; captcha.php liefert {question, token}; gültiger Aufruf → Mail konnte nicht versendet werden ….
Empfänger#
Der Empfänger steht in der Seite (data-recipient) und wird vom Browser mitgeschickt. Ohne Schutz könnte jeder mit einer eigenen Anfrage über Ihren Mailzugang an beliebige Adressen schreiben. Deshalb legt der Export die Datei assets/vn-formrender/recipients.php an.
Syntax
<?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',
);| Regel | Beschreibung |
|---|---|
| Inhalt | alle data-recipient-Werte aller exportierten Seiten und, ab Version 1.3.100, alle Adressen aus …native-form-handler.php?to=…, kleingeschrieben |
| Zeichen | nur unverfängliche Adressen (höchstens 254 Zeichen, ohne Anführungszeichen, Backslash, $, Leerzeichen); sie stehen als einfache PHP-Strings |
| Wer prüft | mailer.php und, ab Version 1.3.100, native-form-handler.php (native-form-handler.php); der Handler erlaubt zusätzlich die eigene Absenderadresse aus der SMTP-Konfiguration |
| Fehlt die Datei | (ältere Exporte) gilt jede gültige Adresse. Exportieren Sie die Seite neu und laden Sie sie hoch, damit die Liste greift |
| Mehrere Empfänger je Formular | nicht vorgesehen: ein Komma-Wert besteht die Adressprüfung nicht |
Für mehrere Empfänger: Weiterleitung im Postfach des Empfängers einrichten, oder mehrere Formulare mit je einer Adresse. Eine Seite darf Formulare mit verschiedenen Empfängern enthalten, alle stehen dann in recipients.php.
config.php (assets/vn-shared)#
assets/vn-shared/config.php hält die Mail-Zugangsdaten. Das Programm erzeugt sie erst beim Export aus den Einstellungen im Programm-Profil (nicht im Projektordner).
Syntax (aus 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 | Bedeutung |
|---|---|
$smtp_host, $smtp_port | Server, Port (Standard 587) |
$smtp_encryption | tls (STARTTLS), ssl (SMTPS), sonst keine |
$smtp_username, $smtp_password | Anmeldung (Pflicht) |
$smtp_from_email, $smtp_from_name | Absender der Mails |
$hmac_secret | Geheimer Schlüssel für das Mathe-Captcha; einmal erzeugt, bleibt über Speichervorgänge stabil |
Die Datei wird nur geschrieben, wenn SMTP eingerichtet ist (oder in der Vorschau). Im Vorschau-Betrieb gehen Mails an einen lokalen Mail-Fänger (.eml-Dateien), nie an den echten Server. Speichert der Nutzer die SMTP-Einstellungen neu, aktualisiert das Programm eine vorhandene publish/assets/vn-shared/config.php sofort.
SMTP-Einstellungen im Programm#
Einstellungen › SMTP (Mailversand): Server, Port, Verschlüsselung, Benutzer, Passwort, Absender-Adresse und -Name. Das Programm prüft vor dem Speichern:
| Regel | Meldung (sinngemäß) |
|---|---|
Server nur als Name, ohne https:// und ohne Schrägstriche | „Beim SMTP-Server nur den Namen eintragen …“ |
| Port 1–65535 (üblich 587 oder 465) | „Der Port muss eine Zahl …“ |
| Absender-Adresse Pflicht, wenn ein Server eingetragen ist | „Bitte eine Absender-E-Mail eintragen“ |
Absender-Adresse muss wie name@example.com aussehen | „Die Absender-E-Mail ist ungültig“ |
Die Zugangsdaten liegen im Programm-Profil (verschlüsselter Speicher), nie im Projekt. Dasselbe config.php lesen mailer.php, captcha.php und native-form-handler.php.
hCaptcha (nur Form Renderer)#
Ein Feld hcaptcha im Formular lädt das Skript https://js.hcaptcha.com/1/api.js von hCaptcha und prüft die Antwort serverseitig gegen https://api.hcaptcha.com/siteverify. Das Secret steht in assets/vn-formrender/config.php ($hcaptcha_secret), erzeugt beim Export aus dem Programm-Profil. Der Site-Key steht im Formular-JSON (hcaptchaSiteKey am Feld).
native-form-handler.php#
Für klassische Formulare ohne JavaScript (ein echtes <form method="post">) liefert der Export assets/vn-formrender/native-form-handler.php mit (zusammen mit allen Dateien des Ordners, sobald ein Formular-Block auf einer Seite liegt).
| Merkmal | Verhalten |
|---|---|
| Aufruf | native-form-handler.php?to=name@example.com als action |
| Empfänger | to aus der Adresse; fehlt er oder ist er keine gültige Adresse, geht die Mail an die Absenderadresse der SMTP-Konfiguration. Ab Version 1.3.100 sendet der Handler nur an Adressen aus recipients.php und an die eigene Absenderadresse (Empfänger) |
| Felder | alle POST-Felder außer website, captcha_*, copy_to_sender, vnmailer_*, h-captcha-response; Feldname = Beschriftung; Werte ohne HTML, höchstens 2000 Zeichen |
| Reply-To | Feld, dessen Name wie email, e-mail, email1 aussieht |
| Steuerfelder | vnmailer_id, vnmailer_subject, vnmailer_copy_subject, vnmailer_copy_intro, vnmailer_hcaptcha_sitekey, captcha_answer, captcha_token, copy_to_sender, website (Honeypot) |
| Antwort | AJAX (X-Requested-With oder Accept: application/json): JSON; sonst Weiterleitung zurück zur Seite (Referer) mit vnmailer=success|error, vnmailer_msg, vnmailer_id |
| IP-Begrenzung | 15 Anfragen je 10 Minuten |
Empfängerliste (ab Version 1.3.100). Der Handler gleicht den Empfänger (to, Groß-/Kleinschreibung egal) mit der Liste in assets/vn-formrender/recipients.php ab. Erlaubt sind die Adressen dieser Liste und immer die eigene Absenderadresse aus der SMTP-Konfiguration; jede andere Adresse beantwortet er mit Dieser Empfänger ist für das Formular nicht freigegeben. Den Inhalt der Liste schreibt der Export: Er sammelt die Adressen aus data-recipient und aus …native-form-handler.php?to=… im HTML aller exportierten Seiten (die Adresse darf URL-kodiert stehen) und legt recipients.php auch dann an, wenn eine Seite den Handler ohne to benutzt (die Liste ist dann leer, es gilt nur die Absenderadresse).
Export-Verhalten#
Findet der Export in irgendeiner Seite class="vn-formrender" oder class="vn-sform-form", geschieht Folgendes:
| Ergebnis | Pfad |
|---|---|
| Versand-Dateien | assets/vn-formrender/ (komplettes Verzeichnis aus vendor/vn-formrender: mailer.php, captcha.php, native-form-handler.php, render.js, PHPMailer) |
| Formular-JSONs | assets/vn-formrender/forms/*.json, dazu forms/.htaccess mit Options -Indexes |
| Empfängerliste | assets/vn-formrender/recipients.php (wenn Adressen gefunden wurden oder eine Seite native-form-handler.php benutzt) |
| hCaptcha-Secret | assets/vn-formrender/config.php (wenn eingerichtet) |
| Zugangsdaten | assets/vn-shared/config.php (wenn SMTP eingerichtet) |
Skript (nur vn-sform) | vendor/vn-sform/vn-sform.js, eingebunden am Seitenende |
Ist SMTP nicht eingerichtet, zeigt der Export einen Hinweis; das Formular antwortet dann mit Formular ist noch nicht konfiguriert.
Formulare mit dem VN Form Editor und dem Form Renderer#
Zusammenspiel#
- Im VN Form Editor (Werkzeug, Fenster mit Palette, Canvas, Eigenschaften, Reiter „Regeln“ und „Vorschau“) bauen Sie das Formular per Drag & Drop.
- Es wird im Projekt gespeichert als
assets/vn-formrender/forms/<name>.json. - Ein Form-Renderer-Block (fünf Designs) trägt den Namen im Panel-Feld
formFile, ein Skript lädt zur Laufzeitrender.js, das die JSON holt (fetch), das Formular aufbaut, Regeln auswertet und übermailer.phpsendet.
Die Formular-JSON#
Syntax
{
"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" } ] }
]
}| Datei | Regel |
|---|---|
| Ort | assets/vn-formrender/forms/<name>.json |
| Name | ^[a-zA-Z0-9_-]{1,60}$ (Programm und Renderer filtern alles andere weg) |
| Mindestinhalt | ein Array fields; fehlt rules, gilt [] |
| Gespeichert wird | { fields, rules }, eingerückt, atomar (temporäre Datei, dann umbenennen) |
Feldeigenschaften#
| Eigenschaft | Typ | Bedeutung |
|---|---|---|
id | Text (f1, f2 …) | Eindeutige Kennung; Ziel und Bedingungen der Regeln verweisen darauf |
type | Text | siehe nächste Tabelle |
label | Text | Beschriftung (Überschrift bei heading, Text bei submit) |
placeholder | Text | Platzhalter bei Text-/Mehrzeilenfeldern |
value | Text | Wert bei hidden |
required | Schalter | Pflichtfeld (consent ist immer Pflicht) |
hiddenByDefault | Schalter | Feld startet unsichtbar (nur Regeln können es zeigen) |
options | Liste | Einträge bei select, radio (Standard ["Option 1","Option 2"]) |
width | Prozent | Breite (calc(<w>% - var(--vfr-gap))); Standard 100; heading, hcaptcha immer 100 % |
linkText, linkUrl, linkSuffix | Text | bei consent: Text, Adresse, Nachsatz („gelesen und akzeptiere sie.“) |
hcaptchaSiteKey | Text | bei hcaptcha |
linkDisplayText, linkDisplayUrl | Text | bei linkdisplay |
Feldtypen#
type | Beschreibung |
|---|---|
text, email, tel, url, number, date | Einzeilige Eingabe (input[type=…]); email wird zusätzlich als Reply-To genutzt |
textarea | Mehrzeiliger Text (optionaler Zeichenzähler) |
select | Auswahlliste aus options |
radio | Optionsgruppe aus options |
checkbox | Einzelne Checkbox |
file | Datei-Upload (Größe maxFileSizeMB), geht als Anhang mit |
hidden | Verstecktes Feld mit value |
heading | Überschrift; bei „mehrseitig“ beginnt sie eine neue Seite |
consent | Datenschutz-Checkbox mit Link (linkText, linkUrl, linkSuffix), immer Pflicht |
copytosender | „Kopie an mich“ (Checkbox, wirkt wie copy_to_sender) |
captcha | Mathe-Sicherheitsabfrage (wie bei vn-sform) |
hcaptcha | hCaptcha (siehe hCaptcha) |
signature | Unterschrift (Zeichenfläche), wird als Bild (PNG) mitgeschickt |
linkdisplay | Reine Link-Anzeige (kein Wert) |
submit | Absenden-Knopf |
Regeln#
Eine Regel beobachtet Felder und wirkt auf ein Zielfeld. Jede Änderung im Formular wertet alle Regeln neu aus (engineApply): Erst wird der Grundzustand hergestellt (hiddenByDefault, required), dann greifen die Regeln, deren Bedingung erfüllt ist.
Syntax
{ "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" }
] }
] }| Eigenschaft | Werte | Bedeutung |
|---|---|---|
target | Feld-id | Zielfeld (bei redirect nicht nötig) |
action | siehe Aktionen | Was geschieht |
value | Text | Wert für setValue, Adresse für redirect |
logic | AND (alle), OR (eine) | Verknüpfung der Bedingungen dieser Ebene |
conditions | Liste | Einträge { field, op, value } oder verschachtelte Gruppen { logic, conditions } |
carryValues | Schalter, Standard an | Bei redirect: alle ausgefüllten Werte als Adressparameter anhängen |
Operatoren#
op | Prüft | Wert nötig |
|---|---|---|
equals / notEquals | Text gleich / ungleich (exakt) | ja |
contains / notContains | enthält / enthält nicht (Groß-/Kleinschreibung egal) | ja |
isEmpty / isNotEmpty | leer / nicht leer | nein |
greaterThan / lessThan | Zahlenvergleich | ja |
checked / notChecked | Checkbox angehakt / nicht | nein |
Radio und Auswahl vergleichen den exakten Options-Text. Eine Checkbox speichert nur an/aus: Verwenden Sie checked, nicht equals "ja". Bedingungsquellen sind Felder mit echtem Wert (text, textarea, email, tel, url, number, select, radio, checkbox, date, file, hidden, copytosender).
Aktionen#
action | Wirkung |
|---|---|
show | Zielfeld einblenden |
hide | Zielfeld ausblenden |
require | Zielfeld zur Pflicht machen |
unrequire | Pflicht aufheben |
enable | Zielfeld aktivieren |
disable | Zielfeld deaktivieren |
setValue | Wert setzen (löst change aus) |
redirect | Weiterleiten zur Adresse in value (nur einmal; Werte als Parameter, wenn carryValues) |
Der Form-Renderer-Block#
Der Block (vn-formrender, fünf Designs: Standard, Hintergrund, Bildrahmen, Fotokarte, Overlay) enthält ein ausgeblendetes Datenelement, ein Ausgabefeld, eine Editor-Vorschau und ein kleines Startskript.
Syntax (Gerüst des Blocks „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>| Teil | Bedeutung |
|---|---|
section.vn-formrender | Erkennung im Export (kopiert vn-formrender/, schreibt recipients.php) |
.vnfr-data[data-…] | Einstellungen für render.js (Tabelle unten) |
.vnfr-out | Hier baut render.js das Formular |
.vnfr-builder-dummy | Statische Vorschau; im Editor sichtbar (#canvas .vn-formrender .vnfr-builder-dummy {display:block}), auf der Seite von render.js ersetzt |
data-vnfr-pending | Das Startskript markiert die Section, bevor es render.js in den <head> setzt; render.js sucht die wartende Section |
data-vnfr-rendered | Von render.js nach dem Aufbau gesetzt |
Das Startskript erkennt den Editor mit document.documentElement.classList.contains('is-builder'). Das Programm setzt diese Klasse nie (siehe Editor-Erkennung); im Editor läuft deshalb der „Live“-Zweig des Startskripts. Die Editor-Vorschau (.vnfr-builder-dummy) bleibt über eine Regel im Canvas-CSS sichtbar.
Einstellungen am .vnfr-data (Namen kleingeschrieben; Wahrheitswerte true/on/1; ein Wert, der noch {{ enthält, zählt als leer):
| Attribut | Standard | Bedeutung |
|---|---|---|
data-formfile | — | Name der JSON (ohne Pfad und Endung; nur [a-zA-Z0-9_-]) |
data-recipient | — | Empfänger |
data-subject | Neue Nachricht über die Webseite | Betreff |
data-copytosender | aus | Kopie an den Absender als Vorgabe |
data-thankyouurl | leer | Danke-Seite |
data-style | standard | Design |
data-cardwidth, data-cardopacity, data-cardbg | 45, 100, #ffffff | Karte (Fotokarte/Overlay) |
data-overlaybtn | Kontakt aufnehmen | Knopftext des Overlay-Designs |
data-inputstyle | boxed | boxed oder underline |
data-inputbg, data-inputbgopacity | #ffffff, 100 | Feldhintergrund |
data-customfont | leer | Google-Font-Name; lädt die Schrift von fonts.googleapis.com |
data-twocolumns | aus | Automatisches 2-Spalten-Layout |
data-mobilekeepwidth | aus | Am Handy eigene Feldbreite behalten |
data-borderless, data-stickyform, data-compactmode, data-syncradius | aus | Randlos, fixiert, kompakt, Radien gekoppelt |
data-shadowlevel | soft | none, soft, medium, strong |
data-showfieldicons | aus | Symbole vor den Beschriftungen |
data-maxfilesizemb | 3 | Dateigrenze im Browser (MB; im Panel 1–8) |
data-captchatransparent | aus | Captcha-Box ohne Hintergrund |
data-livevalidation | aus | Live-Prüfung mit Haken |
data-charcounter | aus | Zeichenzähler bei textarea |
data-showprogressbar | aus | Fortschrittsbalken bei mehreren Überschriften |
data-multistep, data-multistepnexttext, data-multistepbacktext | aus, Weiter, Zurück | Mehrseitig (Überschriften = Seiten) |
data-hcaptchasize, data-hcaptchatheme | normal, light | normal/compact; light/dark |
data-submiticon | none | arrow, check, paperplane |
data-successanimation | aus | Erfolgsanimation |
data-backgroundfullblock | aus | Hintergrund über den ganzen Block (Klasse vnfr-background-fullblock) |
Speichern und Einbinden#
| Schritt | Ort |
|---|---|
| Speichern | Im Form Editor: Namensfeld, „Speichern“; Liste der gespeicherten Formulare zum Öffnen, Neu, Löschen; „Ungespeichert“-Anzeige |
| Austausch | JSON-Import und -Download (zum Mitnehmen in ein anderes Projekt) |
| Einbinden | Block „VN Form Renderer“ einfügen; im Panel unter „Formular-Konfiguration“ den Dateinamen eintragen (das Feld bietet die gespeicherten Namen als Auswahlliste, freie Eingabe möglich) |
| Empfänger | Panel-Feld recipientEmail; Betreff emailSubject; Danke-Seite thankYouUrl |
| Statisch statt dynamisch | Block „Formular (statisch)“ im Reiter „Eigener Code“ (siehe sform-from-editor) |
Beim Export genügt es, den Block auf eine Seite zu legen: Das Programm nimmt forms/<name>.json mit und erzeugt recipients.php.
Sicherheitshinweise#
| Thema | Maßnahme |
|---|---|
| Ausgabe | mailer.php maskiert alle Werte (htmlspecialchars), Zeilenumbrüche im Betreff werden entfernt |
| Empfänger | Nur Adressen aus recipients.php (mailer.php; native-form-handler.php ab Version 1.3.100 ebenso, dort zusätzlich die eigene Absenderadresse); eine Adresse je Formular |
| Spam | Honeypot, IP-Begrenzung (5 je 10 Minuten), optional Mathe-Captcha (signiertes Token) oder hCaptcha |
| Größe | 40 Felder, 8000 Zeichen, 8/15 MB Anhänge |
| Zugangsdaten | config.php mit SMTP-Passwort nur über PHP ausliefern; Passwort nie im Projektordner |
| Datei-Uploads | werden nicht gespeichert, nur angehängt; der Mail-Anbieter prüft Anhänge |
| Pflichtfelder | nur im Browser geprüft, nicht serverseitig |
| Offenes Relay | native-form-handler.php prüft ab Version 1.3.100 gegen recipients.php; ohne diese Datei (Export mit einer älteren Version) sendet er an jede Adresse. Alte Seiten neu exportieren und hochladen |
| Drittanbieter | data-customfont (Google Fonts) und hCaptcha laden ohne Zustimmung |