VN-Designer Entwickler-Dokumentation
08

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.

WegWo das Formular stehtWann 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 BrowserFormulare 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

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>

(aus src/vn-sform.js; dieselbe Form verwenden themes/vn-handwerk-src/components/kontakt1 und gallery-content/vn-app-theme/src/components/signup1)

TeilPflichtAufgabe
form.vn-sform-formjaErkennungsmerkmal. 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 FeldEin Feld samt Beschriftung; data-type bestimmt die Auswertung
.vn-sform-labeljaBeschriftung; ihr Text wird zum Namen des Felds in der Mail
div.vn-sform-hp mit input[name="website"]jaHoneypot (Spam-Falle), siehe Spam-Schutz
button.vn-sform-enterempfohlenUnsichtbarer Absende-Knopf, damit Enter im Feld absendet
div.vn-sform-statusjaMeldungsfläche (hidden), siehe Meldungen
a[data-vn-sform-submit]jaDer Absenden-Knopf
novalidatejaDie Prüfung übernimmt das Skript (eigene Fehlermeldungen unter den Feldern)

Das form-Element: data-Attribute#

AttributTyp/WerteStandardBedeutung
data-recipientE-Mail-Adresse—Empfänger; genau eine Adresse (siehe Empfänger)
data-subjectTextNeue Nachricht über die WebseiteBetreff der Mail (höchstens 150 Zeichen, Zeilenumbrüche entfernt)
data-successTextDanke für deine Nachricht! (bei lang="en": Thank you for your message!)Meldung nach erfolgreichem Absenden
data-thankyouAdresseleerDanke-Seite: ist sie gesetzt, wird dorthin weitergeleitet statt die Meldung zu zeigen
data-mailerPfadassets/vn-formrender/mailer.phpAdresse des Versand-Skripts, relativ zur Seite; captcha.php wird daraus abgeleitet (mailer.php… → captcha.php)
data-vn-sform-ready1—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-typeEingabeelementWert in der Mail
text, tel, url, number, dateinput.vn-sform-input[type=…]eingegebener Text (getrimmt)
emailinput[type=email]Text; die erste gültige E-Mail-Adresse wird Reply-To und Ziel der Absenderkopie
textareatextarea.vn-sform-input.vn-sform-textareaText
selectselect.vn-sform-input.vn-sform-selectgewählter value
radiodiv.vn-sform-choices mit mehreren input[type=radio] (gleicher name)gewählter value; Pflicht, wenn der erste Radio required trägt
checkboxinput[type=checkbox]Ja oder Nein
consentinput[type=checkbox][required] (Datenschutz)Ja/Nein; immer Pflicht
copytosenderinput[type=checkbox][data-vn-copytosender]nicht in der Mail; schaltet die Kopie an den Absender ein
fileinput.vn-sform-file[type=file]Datei als Anhang; in der Mail Name und Größe
captchasiehe Sicherheitsabfragenicht in der Mail
headingh3.vn-sform-heading (Feld heißt vn-sform-field vn-sform-heading-wrap)wird übersprungen
submita.btn.vn-sform-submit[data-vn-sform-submit]wird übersprungen
(ohne Feld) input[type=hidden]name, value, data-labelEintrag unter data-label (sonst name), wenn ein Wert da ist

Beispiele (aus 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>

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.

AngabeWertBedeutung
style="--span:N"1–12Spaltenzahl; 6 = halbe Breite, 12 = ganze Zeile
aus dem Formular-Editorwidth 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 leerBitte ausfüllen.
E-Mail-Feld mit ungültiger AdresseBitte eine gültige E-Mail-Adresse eingeben.
Pflicht-Checkbox nicht angehaktBitte bestätigen.
Radiogruppe ohne Wahl (erster Radio required)Bitte auswählen.
Pflicht-Datei fehltBitte eine Datei wählen.
Datei größer als 3 MBDie Datei ist zu groß (max. 3 MB).
Mathe-Feld leerBitte 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

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>
AttributBedeutung
data-vn-sform-submitKlick sendet das Formular (preventDefault); das Skript setzt dabei vn-sform-busy auf den Knopf (kein Doppel-Klick)
a.btnDer Knopf ist ein normaler, per Klick änderbarer Button (Farbe, Beschriftung, Symbol; siehe Buttons)
.vn-sform-enterZusä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).

SchutzWoBeschreibung
Honeypot websiteFormular + ServerNicht leer = stiller Scheinerfolg
Mathe-SicherheitsabfrageFeldtyp captchaNur wenn das Formular das Feld enthält
IP-BegrenzungServerhöchstens 5 Anfragen je 10 Minuten je Besucheradresse (Antwort Zu viele Anfragen, bitte später erneut versuchen.)
GrößenbegrenzungServerhöchstens 40 Felder, zusammen 8000 Zeichen (Namen + Werte)
EmpfängerlisteServernur Adressen aus recipients.php (Empfänger)

Mathe-Sicherheitsabfrage#

Syntax

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>
AttributBedeutung
data-vn-captcha-qHier schreibt das Skript die Rechenaufgabe hinein (a + b = ?, Zahlen 1–9)
data-vn-captcha-answerDas Antwortfeld
data-vn-captcha-tokenVerstecktes 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#

FallAnzeige
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 …)
NetzwerkfehlerDas 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.

GrenzeWertWo
Größe je Datei im Browser3 MBvn-sform.js (Meldung beim Wählen)
Größe je Datei auf dem Server8 MBmailer.php (Datei zu groß (max. 8 MB).)
Alle Anhänge zusammen15 MBmailer.php
Typenkeine EinschränkungDer 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):

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)ArtBedeutung
recipientTextEmpfänger (an data-recipient)
subjectTextBetreff (data-subject)
successTextTextErfolgsmeldung (data-success)
thankYouUrlTextDanke-Seite (data-thankyou)
padding, maxWidth, align, gapZahlen/AuswahlAbstand, Höchstbreite, Ausrichtung, Feldabstand
fieldStyleoutline, filled, lineAussehen der Felder
radius, fieldSizeZahl, sm/md/lgRundung, Größe
borderColor, fieldBg, focusColorFarbeRahmen, Hintergrund, Fokus
bgColor, labelColor, textColor, errorColor, okColorFarbeFlächen- und Textfarben
btnAlignleft, center, right, fullAusrichtung 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:

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>

Statisches Formular aus dem Formular-Editor#

Der Baustein „Formular (statisch)“ (createSformBlockEntry) übernimmt die Felder eines im VN Form Editor gebauten Formulars als fertiges HTML.

GruppeFeldtypen
Übernommentext, 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 &#123;&#123; 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 }.

SchrittPrüfungAntwort bei Verstoß
1Methode muss POST seinUngültige Anfrage-Methode.
2../vn-shared/config.php muss existieren und $hmac_secret, $smtp_host, $smtp_username, $smtp_password enthaltenFormular ist noch nicht konfiguriert …
3Inhalt lesen (JSON oder multipart)Ungültige Anfrage.
4Honeypot website nicht leerErfolg wird vorgetäuscht, es wird nichts gesendet
5hCaptcha oder Mathe-Captcha (je nachdem, was mitgeschickt wurde)Sicherheitsabfrage … / hCaptcha-Prüfung fehlgeschlagen …
6IP-Begrenzung: 5 Anfragen je 10 Minuten (Datei in sys_get_temp_dir())Zu viele Anfragen, bitte später erneut versuchen.
7recipient muss eine gültige einzelne E-Mail-Adresse seinKein gültiger Empfänger konfiguriert.
8Adresse muss in recipients.php stehen (falls die Datei existiert)Dieser Empfänger ist für das Formular nicht freigegeben.
9Es muss Felder oder Dateien geben; höchstens 40 Felder, 8000 ZeichenKeine Formulardaten übermittelt. / Eingabe zu lang.
10Dateien: 8 MB je Datei, 15 MB gesamt, nur echte UploadsDatei zu groß … / Anhänge zusammen zu groß …
11Betreff: höchstens 150 Zeichen, \r/\n entfernt (Header-Injection)—
12Mail: HTML-Tabelle (Feldname, Wert; Werte mit htmlspecialchars und nl2br) und Textfassung; Reply-To nur bei gültiger AdresseMail konnte nicht versendet werden, bitte später erneut versuchen.
13Optional Kopie an den AbsenderFehler 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
<?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',
);
RegelBeschreibung
Inhaltalle data-recipient-Werte aller exportierten Seiten und, ab Version 1.3.100, alle Adressen aus …native-form-handler.php?to=…, kleingeschrieben
Zeichennur unverfängliche Adressen (höchstens 254 Zeichen, ohne Anführungszeichen, Backslash, $, Leerzeichen); sie stehen als einfache PHP-Strings
Wer prüftmailer.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 Formularnicht 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
<?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 = "…";
VariableBedeutung
$smtp_host, $smtp_portServer, Port (Standard 587)
$smtp_encryptiontls (STARTTLS), ssl (SMTPS), sonst keine
$smtp_username, $smtp_passwordAnmeldung (Pflicht)
$smtp_from_email, $smtp_from_nameAbsender der Mails
$hmac_secretGeheimer 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:

RegelMeldung (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).

MerkmalVerhalten
Aufrufnative-form-handler.php?to=name@example.com als action
Empfängerto 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)
Felderalle POST-Felder außer website, captcha_*, copy_to_sender, vnmailer_*, h-captcha-response; Feldname = Beschriftung; Werte ohne HTML, höchstens 2000 Zeichen
Reply-ToFeld, dessen Name wie email, e-mail, email1 aussieht
Steuerfeldervnmailer_id, vnmailer_subject, vnmailer_copy_subject, vnmailer_copy_intro, vnmailer_hcaptcha_sitekey, captcha_answer, captcha_token, copy_to_sender, website (Honeypot)
AntwortAJAX (X-Requested-With oder Accept: application/json): JSON; sonst Weiterleitung zurück zur Seite (Referer) mit vnmailer=success|error, vnmailer_msg, vnmailer_id
IP-Begrenzung15 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:

ErgebnisPfad
Versand-Dateienassets/vn-formrender/ (komplettes Verzeichnis aus vendor/vn-formrender: mailer.php, captcha.php, native-form-handler.php, render.js, PHPMailer)
Formular-JSONsassets/vn-formrender/forms/*.json, dazu forms/.htaccess mit Options -Indexes
Empfängerlisteassets/vn-formrender/recipients.php (wenn Adressen gefunden wurden oder eine Seite native-form-handler.php benutzt)
hCaptcha-Secretassets/vn-formrender/config.php (wenn eingerichtet)
Zugangsdatenassets/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#

  1. Im VN Form Editor (Werkzeug, Fenster mit Palette, Canvas, Eigenschaften, Reiter „Regeln“ und „Vorschau“) bauen Sie das Formular per Drag & Drop.
  2. Es wird im Projekt gespeichert als assets/vn-formrender/forms/<name>.json.
  3. Ein Form-Renderer-Block (fünf Designs) trägt den Namen im Panel-Feld formFile, ein Skript lädt zur Laufzeit render.js, das die JSON holt (fetch), das Formular aufbaut, Regeln auswertet und über mailer.php sendet.

Die Formular-JSON#

Syntax

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" } ] }
  ]
}
DateiRegel
Ortassets/vn-formrender/forms/<name>.json
Name^[a-zA-Z0-9_-]{1,60}$ (Programm und Renderer filtern alles andere weg)
Mindestinhaltein Array fields; fehlt rules, gilt []
Gespeichert wird{ fields, rules }, eingerückt, atomar (temporäre Datei, dann umbenennen)

Feldeigenschaften#

EigenschaftTypBedeutung
idText (f1, f2 …)Eindeutige Kennung; Ziel und Bedingungen der Regeln verweisen darauf
typeTextsiehe nächste Tabelle
labelTextBeschriftung (Überschrift bei heading, Text bei submit)
placeholderTextPlatzhalter bei Text-/Mehrzeilenfeldern
valueTextWert bei hidden
requiredSchalterPflichtfeld (consent ist immer Pflicht)
hiddenByDefaultSchalterFeld startet unsichtbar (nur Regeln können es zeigen)
optionsListeEinträge bei select, radio (Standard ["Option 1","Option 2"])
widthProzentBreite (calc(<w>% - var(--vfr-gap))); Standard 100; heading, hcaptcha immer 100 %
linkText, linkUrl, linkSuffixTextbei consent: Text, Adresse, Nachsatz („gelesen und akzeptiere sie.“)
hcaptchaSiteKeyTextbei hcaptcha
linkDisplayText, linkDisplayUrlTextbei linkdisplay

Feldtypen#

typeBeschreibung
text, email, tel, url, number, dateEinzeilige Eingabe (input[type=…]); email wird zusätzlich als Reply-To genutzt
textareaMehrzeiliger Text (optionaler Zeichenzähler)
selectAuswahlliste aus options
radioOptionsgruppe aus options
checkboxEinzelne Checkbox
fileDatei-Upload (Größe maxFileSizeMB), geht als Anhang mit
hiddenVerstecktes Feld mit value
headingÜberschrift; bei „mehrseitig“ beginnt sie eine neue Seite
consentDatenschutz-Checkbox mit Link (linkText, linkUrl, linkSuffix), immer Pflicht
copytosender„Kopie an mich“ (Checkbox, wirkt wie copy_to_sender)
captchaMathe-Sicherheitsabfrage (wie bei vn-sform)
hcaptchahCaptcha (siehe hCaptcha)
signatureUnterschrift (Zeichenfläche), wird als Bild (PNG) mitgeschickt
linkdisplayReine Link-Anzeige (kein Wert)
submitAbsenden-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

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" }
    ] }
  ] }
EigenschaftWerteBedeutung
targetFeld-idZielfeld (bei redirect nicht nötig)
actionsiehe AktionenWas geschieht
valueTextWert für setValue, Adresse für redirect
logicAND (alle), OR (eine)Verknüpfung der Bedingungen dieser Ebene
conditionsListeEinträge { field, op, value } oder verschachtelte Gruppen { logic, conditions }
carryValuesSchalter, Standard anBei redirect: alle ausgefüllten Werte als Adressparameter anhängen

Operatoren#

opPrüftWert nötig
equals / notEqualsText gleich / ungleich (exakt)ja
contains / notContainsenthält / enthält nicht (Groß-/Kleinschreibung egal)ja
isEmpty / isNotEmptyleer / nicht leernein
greaterThan / lessThanZahlenvergleichja
checked / notCheckedCheckbox angehakt / nichtnein

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#

actionWirkung
showZielfeld einblenden
hideZielfeld ausblenden
requireZielfeld zur Pflicht machen
unrequirePflicht aufheben
enableZielfeld aktivieren
disableZielfeld deaktivieren
setValueWert setzen (löst change aus)
redirectWeiterleiten 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“)

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>
TeilBedeutung
section.vn-formrenderErkennung im Export (kopiert vn-formrender/, schreibt recipients.php)
.vnfr-data[data-…]Einstellungen für render.js (Tabelle unten)
.vnfr-outHier baut render.js das Formular
.vnfr-builder-dummyStatische Vorschau; im Editor sichtbar (#canvas .vn-formrender .vnfr-builder-dummy {display:block}), auf der Seite von render.js ersetzt
data-vnfr-pendingDas Startskript markiert die Section, bevor es render.js in den <head> setzt; render.js sucht die wartende Section
data-vnfr-renderedVon 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):

AttributStandardBedeutung
data-formfile—Name der JSON (ohne Pfad und Endung; nur [a-zA-Z0-9_-])
data-recipient—Empfänger
data-subjectNeue Nachricht über die WebseiteBetreff
data-copytosenderausKopie an den Absender als Vorgabe
data-thankyouurlleerDanke-Seite
data-stylestandardDesign
data-cardwidth, data-cardopacity, data-cardbg45, 100, #ffffffKarte (Fotokarte/Overlay)
data-overlaybtnKontakt aufnehmenKnopftext des Overlay-Designs
data-inputstyleboxedboxed oder underline
data-inputbg, data-inputbgopacity#ffffff, 100Feldhintergrund
data-customfontleerGoogle-Font-Name; lädt die Schrift von fonts.googleapis.com
data-twocolumnsausAutomatisches 2-Spalten-Layout
data-mobilekeepwidthausAm Handy eigene Feldbreite behalten
data-borderless, data-stickyform, data-compactmode, data-syncradiusausRandlos, fixiert, kompakt, Radien gekoppelt
data-shadowlevelsoftnone, soft, medium, strong
data-showfieldiconsausSymbole vor den Beschriftungen
data-maxfilesizemb3Dateigrenze im Browser (MB; im Panel 1–8)
data-captchatransparentausCaptcha-Box ohne Hintergrund
data-livevalidationausLive-Prüfung mit Haken
data-charcounterausZeichenzähler bei textarea
data-showprogressbarausFortschrittsbalken bei mehreren Überschriften
data-multistep, data-multistepnexttext, data-multistepbacktextaus, Weiter, ZurückMehrseitig (Überschriften = Seiten)
data-hcaptchasize, data-hcaptchathemenormal, lightnormal/compact; light/dark
data-submiticonnonearrow, check, paperplane
data-successanimationausErfolgsanimation
data-backgroundfullblockausHintergrund über den ganzen Block (Klasse vnfr-background-fullblock)

Speichern und Einbinden#

SchrittOrt
SpeichernIm Form Editor: Namensfeld, „Speichern“; Liste der gespeicherten Formulare zum Öffnen, Neu, Löschen; „Ungespeichert“-Anzeige
AustauschJSON-Import und -Download (zum Mitnehmen in ein anderes Projekt)
EinbindenBlock „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ängerPanel-Feld recipientEmail; Betreff emailSubject; Danke-Seite thankYouUrl
Statisch statt dynamischBlock „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#

ThemaMaßnahme
Ausgabemailer.php maskiert alle Werte (htmlspecialchars), Zeilenumbrüche im Betreff werden entfernt
EmpfängerNur 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
SpamHoneypot, IP-Begrenzung (5 je 10 Minuten), optional Mathe-Captcha (signiertes Token) oder hCaptcha
Größe40 Felder, 8000 Zeichen, 8/15 MB Anhänge
Zugangsdatenconfig.php mit SMTP-Passwort nur über PHP ausliefern; Passwort nie im Projektordner
Datei-Uploadswerden nicht gespeichert, nur angehängt; der Mail-Anbieter prüft Anhänge
Pflichtfeldernur im Browser geprüft, nicht serverseitig
Offenes Relaynative-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
Drittanbieterdata-customfont (Google Fonts) und hCaptcha laden ohne Zustimmung