Forms
The static form (vn-sform) with all its markers, the shared PHP sending (mailer.php, config.php, recipients.php, SMTP), spam protection, and the VN Form Editor with the Form Renderer (field types, rules, saving, embedding).
Overview#
There are two ways to get a working form. Both send through the same PHP (mailer.php), whose credentials the program generates on export.
| Way | Where the form lives | When to choose it |
|---|---|---|
Static form (vn-sform) | Finished HTML in the block (fields directly in the template) | Contact forms in themes and blocks; all texts editable by click; appearance via panel and CSS |
Form Renderer (vn-formrender) | A JSON file created by the VN Form Editor; the block builds the form only in the browser | Forms with rules (show/hide), several steps, signature, hCaptcha |
Requirements: the website is hosted on a server with PHP. The pages themselves may be named .html; only the PHP in assets/vn-formrender/ must be executed. You set the sender address and mail server (SMTP) in the program (see SMTP settings).
The static form: vn-sform#
Basic structure#
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>(from src/vn-sform.js; themes/vn-handwerk-src/components/kontakt1 and gallery-content/vn-app-theme/src/components/signup1 use the same form)
| Part | Required | Purpose |
|---|---|---|
form.vn-sform-form | yes | Identifying mark. Only a <form> with this class is picked up by the script and recognized by the export (class="… vn-sform-form …") |
div.vn-sform-field[data-type] | yes, per field | One field with its label; data-type determines how it is evaluated |
.vn-sform-label | yes | Label; its text becomes the name of the field in the mail |
div.vn-sform-hp with input[name="website"] | yes | Honeypot (spam trap), see Spam protection |
button.vn-sform-enter | recommended | Invisible submit button so that Enter in a field submits |
div.vn-sform-status | yes | Message area (hidden), see Messages |
a[data-vn-sform-submit] | yes | The submit button |
novalidate | yes | The script does the validation (own error messages below the fields) |
The form element: data attributes#
| Attribute | Type/values | Default | Meaning |
|---|---|---|---|
data-recipient | email address | — | Recipient; exactly one address (see Recipients) |
data-subject | text | Neue Nachricht über die Webseite | Subject of the mail (at most 150 characters, line breaks removed) |
data-success | text | Danke für deine Nachricht! (with lang="en": Thank you for your message!) | Message after a successful submit |
data-thankyou | address | empty | Thank-you page: if set, the visitor is redirected there instead of the message being shown |
data-mailer | path | assets/vn-formrender/mailer.php | Address of the sending script, relative to the page; captcha.php is derived from it (mailer.php… → captcha.php) |
data-vn-sform-ready | 1 | — | Set by the script: the form is initialized (do not set by hand) |
Field types#
Every field is a div.vn-sform-field with data-type. The script collects all .vn-sform-field[data-type] and reads the label (.vn-sform-label) and the first input element (input:not([type=radio]), textarea, select) from each.
data-type | Input element | Value in the mail |
|---|---|---|
text, tel, url, number, date | input.vn-sform-input[type=…] | entered text (trimmed) |
email | input[type=email] | text; the first valid email address becomes the Reply-To and the target of the sender copy |
textarea | textarea.vn-sform-input.vn-sform-textarea | text |
select | select.vn-sform-input.vn-sform-select | selected value |
radio | div.vn-sform-choices with several input[type=radio] (same name) | selected value; required if the first radio has required |
checkbox | input[type=checkbox] | Ja or Nein (yes or no) |
consent | input[type=checkbox][required] (privacy) | Ja/Nein; always required |
copytosender | input[type=checkbox][data-vn-copytosender] | not in the mail; switches on the copy to the sender |
file | input.vn-sform-file[type=file] | file as an attachment; name and size in the mail |
captcha | see Security question | not in the mail |
heading | h3.vn-sform-heading (the field is called vn-sform-field vn-sform-heading-wrap) | is skipped |
submit | a.btn.vn-sform-submit[data-vn-sform-submit] | is skipped |
(no field) input[type=hidden] | name, value, data-label | entry under data-label (otherwise name) if a value is present |
Examples (from 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>Grid: --span#
The field grid has 12 columns (.vn-sform-fields { display:grid; grid-template-columns: repeat(12, 1fr) }). The width of a field is set as a style variable on the field.
| Value | Range | Meaning |
|---|---|---|
style="--span:N" | 1–12 | Number of columns; 6 = half width, 12 = full row |
| from the form editor | width in % | becomes --span = round(width/100*12) (1–12; invalid = 12) |
| Phone (below 640 px) | — | every field becomes 12 columns wide |
Themes with a Bootstrap grid (row g-3, col-sm-6) work just as well: the script reads only .vn-sform-field[data-type], not the columns (example kontakt1 in the VN Handwerk theme).
Required fields#
A field is required through the required attribute on the input element. The asterisk is purely visual (<span class="vn-sform-req" aria-hidden="true"> *</span> in the label); the script removes it from the field name in the mail.
| Check (in the browser, before sending) | Message |
|---|---|
| Required field empty | Bitte ausfüllen. (Please fill in.) |
| Email field with an invalid address | Bitte eine gültige E-Mail-Adresse eingeben. (Please enter a valid email address.) |
| Required checkbox not ticked | Bitte bestätigen. (Please confirm.) |
Radio group without a choice (first radio required) | Bitte auswählen. (Please choose.) |
| Required file missing | Bitte eine Datei wählen. (Please choose a file.) |
| File larger than 3 MB | Die Datei ist zu groß (max. 3 MB). (The file is too large.) |
| Math field empty | Bitte ausfüllen. (Please fill in.) |
Fields with errors get the class vn-sform-invalid; a <p class="vn-sform-error"> appears below them. The first invalid field receives focus. The messages in the table are hard-coded in German in the script; only the hints of the math security question and the fallback success message follow the lang on <html> (en = English). Set your own texts for success and redirect through data-success and data-thankyou.
Submit button#
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>| Attribute | Meaning |
|---|---|
data-vn-sform-submit | A click submits the form (preventDefault); the script sets vn-sform-busy on the button (no double click) |
a.btn | The button is a normal button editable by click (color, label, icon; see Buttons) |
.vn-sform-enter | Additional invisible button[type=submit] so that Enter in a field submits |
Spam protection: honeypot#
The field input[name="website"] in div.vn-sform-hp is invisible to humans (moved out of view, tabindex="-1"). If a bot fills it in, mailer.php pretends success without sending anything (bots notice no difference).
| Protection | Where | Description |
|---|---|---|
Honeypot website | Form + server | Not empty = silent fake success |
| Math security question | Field type captcha | Only if the form contains the field |
| IP limit | Server | at most 5 requests per 10 minutes per visitor address (response Zu viele Anfragen, bitte später erneut versuchen., meaning “Too many requests, please try again later.”) |
| Size limit | Server | at most 40 fields, 8000 characters in total (names + values) |
| Recipient list | Server | only addresses from recipients.php (Recipients) |
Math security question#
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>| Attribute | Meaning |
|---|---|
data-vn-captcha-q | The script writes the math question here (a + b = ?, numbers 1–9) |
data-vn-captcha-answer | The answer field |
data-vn-captcha-token | Hidden field for the signed token |
Flow: the script fetches question and token from captcha.php (?t=<time>, no caching). The token is base64({a,b,exp}) + "." + HMAC-SHA256, signed with the secret key from config.php (hmac_secret), valid for 10 minutes; the result appears nowhere in plain text. mailer.php checks signature, expiry and sum. After every submit a new question is loaded. If captcha.php is unreachable, the question shows nicht verfügbar (not available).
Messages and redirect#
| Case | Display |
|---|---|
Success (HTTP 200, success: true) | Without data-thankyou: the form is cleared, .vn-sform-status.vn-sform-ok shows data-success (otherwise the server’s response, otherwise Danke für deine Nachricht!). With data-thankyou: redirect there |
| Error from the server | .vn-sform-status.vn-sform-fail with the server’s message (for example Zu viele Anfragen …) |
| Network error | Das Formular konnte nicht gesendet werden. Bitte später erneut versuchen. (The form could not be sent. Please try again later.) |
The .vn-sform-status area is hidden by default. The classes vn-sform-ok and vn-sform-fail determine color and border.
File uploads#
A field data-type="file" sends the file as an attachment of the mail. If files are chosen, the script sends multipart/form-data instead of JSON.
| Limit | Value | Where |
|---|---|---|
| Size per file in the browser | 3 MB | vn-sform.js (message when choosing) |
| Size per file on the server | 8 MB | mailer.php (Datei zu groß (max. 8 MB).) |
| All attachments together | 15 MB | mailer.php |
| Types | no restriction | The file name is reduced to basename; the file is not stored, only attached to the mail |
Copy to the sender#
The field data-type="copytosender" (checkbox with data-vn-copytosender) switches on a copy: the sender receives the same mail at the Reply-To address (the first valid email from an email field), with the subject suffixed “ (Kopie deiner Nachricht)”. A failed copy does not report an error.
Data format to the server#
Without files the script sends 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": "…" }
}With files it sends multipart/form-data with the fields recipient, subject, reply_to, copy_to_sender (1 or empty), website, captcha_answer, captcha_token, fields_json (JSON text of the same fields), files[], file_labels[]. The response is always JSON: { "success": true|false, "message": "…" } (HTTP 200 on success, otherwise 400/500).
The keys in fields are the labels (without the asterisk). Identical labels are kept distinguishable by appended spaces.
Properties panel of the block#
The finished block “Form (static)” comes with these fields (name in vn-parameters); you need them only if you build your own block with a panel:
Field (name) | Kind | Meaning |
|---|---|---|
recipient | text | Recipient (into data-recipient) |
subject | text | Subject (data-subject) |
successText | text | Success message (data-success) |
thankYouUrl | text | Thank-you page (data-thankyou) |
padding, maxWidth, align, gap | numbers/choice | Spacing, maximum width, alignment, field gap |
fieldStyle | outline, filled, line | Appearance of the fields |
radius, fieldSize | number, sm/md/lg | Rounding, size |
borderColor, fieldBg, focusColor | color | Border, background, focus |
bgColor, labelColor, textColor, errorColor, okColor | color | Surface and text colors |
btnAlign | left, center, right, full | Alignment of the submit button |
Example: contact form in a theme#
From themes/vn-handwerk-src/components/kontakt1/template.html (shortened). It uses Bootstrap classes for the grid and hides the labels visually (visually-hidden) but shows placeholders:
<form class="vn-sform-form" novalidate data-recipient="{{recipient}}" data-subject="{{subject}}"
data-success="{{successText}}" data-thankyou="" data-mailer="assets/vn-formrender/mailer.php"
aria-label="Kontaktformular">
<div class="row g-3">
<div class="col-sm-6 vn-sform-field" data-type="text">
<p class="vn-sform-label visually-hidden" id="{{vn-id}}-f1-l">Ihr Name<span class="vn-sform-req" aria-hidden="true"> *</span></p>
<input type="text" class="form-control hw-in vn-sform-input" placeholder="Ihr Name"
id="{{vn-id}}-f1" name="f1" aria-labelledby="{{vn-id}}-f1-l" required>
</div>
<div class="col-12 vn-sform-field" data-type="email">
<p class="vn-sform-label visually-hidden" id="{{vn-id}}-f3-l">E-Mail-Adresse<span class="vn-sform-req" aria-hidden="true"> *</span></p>
<input type="email" class="form-control hw-in vn-sform-input" placeholder="E-Mail-Adresse"
id="{{vn-id}}-f3" name="f3" aria-labelledby="{{vn-id}}-f3-l" autocomplete="email" required>
</div>
<div class="col-12 vn-sform-field" data-type="textarea">
<p class="vn-sform-label visually-hidden" id="{{vn-id}}-f5-l">Ihre Nachricht<span class="vn-sform-req" aria-hidden="true"> *</span></p>
<textarea class="form-control hw-in vn-sform-input vn-sform-textarea" rows="4" placeholder="Ihre Nachricht"
id="{{vn-id}}-f5" name="f5" aria-labelledby="{{vn-id}}-f5-l" required></textarea>
</div>
<div class="col-12 vn-sform-field vn-sform-submit-wrap" data-type="submit">
<a href="#" role="button" class="btn hw-b hw-b-solid w-100" data-vn-sform-submit>Anfrage senden</a>
</div>
</div>
<div class="vn-sform-hp" aria-hidden="true"><label>Bitte leer lassen<input type="text" name="website" tabindex="-1" autocomplete="off"></label></div>
<button type="submit" class="vn-sform-enter" tabindex="-1" aria-hidden="true"></button>
<div class="vn-sform-status" role="status" aria-live="polite" hidden></div>
</form>Static form from the form editor#
The block “Form (static)” (createSformBlockEntry) takes over the fields of a form built in the VN Form Editor as finished HTML.
| Group | Field types |
|---|---|
| Taken over | text, textarea, email, tel, url, number, date, select, radio, checkbox, file, hidden, heading, submit, consent, copytosender, captcha |
| Not taken over (only in the Form Renderer) | hcaptcha, signature (signature), linkdisplay (link display), rules, multi-step forms |
Without a submit field the block adds a button “Submit”. Field numbers (f1, f2 …) are reassigned consecutively; {{ in the field text is written as {{ so that the text is never evaluated as a placeholder.
Server side#
mailer.php#
The shared sending script assets/vn-formrender/mailer.php (PHPMailer, SMTP). The response is always JSON { success, message }.
| Step | Check | Response on violation |
|---|---|---|
| 1 | Method must be POST | Ungültige Anfrage-Methode. |
| 2 | ../vn-shared/config.php must exist and contain $hmac_secret, $smtp_host, $smtp_username, $smtp_password | Formular ist noch nicht konfiguriert … |
| 3 | Read the content (JSON or multipart) | Ungültige Anfrage. |
| 4 | Honeypot website not empty | Success is faked, nothing is sent |
| 5 | hCaptcha or math captcha (depending on what was sent) | Sicherheitsabfrage … / hCaptcha-Prüfung fehlgeschlagen … |
| 6 | IP limit: 5 requests per 10 minutes (file in sys_get_temp_dir()) | Zu viele Anfragen, bitte später erneut versuchen. |
| 7 | recipient must be a valid single email address | Kein gültiger Empfänger konfiguriert. |
| 8 | Address must be in recipients.php (if the file exists) | Dieser Empfänger ist für das Formular nicht freigegeben. |
| 9 | There must be fields or files; at most 40 fields, 8000 characters | Keine Formulardaten übermittelt. / Eingabe zu lang. |
| 10 | Files: 8 MB per file, 15 MB in total, real uploads only | Datei zu groß … / Anhänge zusammen zu groß … |
| 11 | Subject: at most 150 characters, \r/\n removed (header injection) | — |
| 12 | Mail: HTML table (field name, value; values with htmlspecialchars and nl2br) and a text version; Reply-To only with a valid address | Mail konnte nicht versendet werden, bitte später erneut versuchen. |
| 13 | Optional copy to the sender | Errors of the copy are ignored |
Empty fields are not included in the mail. Fatal PHP errors are caught by a shutdown handler, which returns JSON instead of an empty 500 page (with a debug field and location).
Verified (PHP 8.3, own test server, SMTP deliberately unreachable): several addresses separated by a comma → Kein gültiger Empfänger konfiguriert.; a foreign address with an existing recipients.php → not approved; honeypot → 200 with fake success; wrong captcha token → Sicherheitsabfrage ungültig …; captcha.php returns {question, token}; a valid call → Mail konnte nicht versendet werden ….
Recipients#
The recipient is stored in the page (data-recipient) and sent along by the browser. Without protection, anyone could use their own request to write to arbitrary addresses through your mail access. That is why the export creates the file assets/vn-formrender/recipients.php.
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',
);| Rule | Description |
|---|---|
| Content | all data-recipient values of all exported pages and, from version 1.3.100, all addresses from …native-form-handler.php?to=…, in lowercase |
| Characters | only harmless addresses (at most 254 characters, without quotation marks, backslash, $, spaces); they are stored as simple PHP strings |
| Who checks | mailer.php and, from version 1.3.100, native-form-handler.php (native-form-handler.php); the handler additionally allows the own sender address from the SMTP configuration |
| If the file is missing | (older exports) any valid address is accepted. Export the page again and upload it so that the list takes effect |
| Several recipients per form | not provided for: a comma-separated value fails the address check |
For several recipients: set up forwarding in the recipient’s mailbox, or use several forms with one address each. A page may contain forms with different recipients; all of them are then listed in recipients.php.
config.php (assets/vn-shared)#
assets/vn-shared/config.php holds the mail credentials. The program generates it only on export from the settings in the program profile (not in the project folder).
Syntax (from 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 | Meaning |
|---|---|
$smtp_host, $smtp_port | Server, port (default 587) |
$smtp_encryption | tls (STARTTLS), ssl (SMTPS), otherwise none |
$smtp_username, $smtp_password | Login (required) |
$smtp_from_email, $smtp_from_name | Sender of the mails |
$hmac_secret | Secret key for the math captcha; generated once, stays stable across saves |
The file is written only if SMTP is set up (or in the preview). In preview mode, mails go to a local mail catcher (.eml files), never to the real server. If the user saves the SMTP settings again, the program updates an existing publish/assets/vn-shared/config.php immediately.
SMTP settings in the program#
Settings › SMTP (mail sending): server, port, encryption, user, password, sender address and name. Before saving, the program checks:
| Rule | Message (approximate) |
|---|---|
Server only as a name, without https:// and without slashes | “For the SMTP server, enter only the host name …” |
| Port 1–65535 (usually 587 or 465) | “The port must be a number …” |
| Sender address required if a server is entered | “Please enter a sender email address” |
Sender address must look like name@example.com | “The sender email address is invalid” |
The credentials are stored in the program profile (encrypted storage), never in the project. mailer.php, captcha.php and native-form-handler.php all read the same config.php.
hCaptcha (Form Renderer only)#
A field hcaptcha in the form loads the script https://js.hcaptcha.com/1/api.js from hCaptcha and checks the response on the server against https://api.hcaptcha.com/siteverify. The secret is stored in assets/vn-formrender/config.php ($hcaptcha_secret), generated on export from the program profile. The site key is stored in the form JSON (hcaptchaSiteKey on the field).
native-form-handler.php#
For classic forms without JavaScript (a real <form method="post">), the export ships assets/vn-formrender/native-form-handler.php (together with all files of the folder as soon as a form block is on a page).
| Feature | Behavior |
|---|---|
| Call | native-form-handler.php?to=name@example.com as action |
| Recipient | to from the address; if it is missing or not a valid address, the mail goes to the sender address of the SMTP configuration. From version 1.3.100 the handler sends only to addresses from recipients.php and to its own sender address (Recipients) |
| Fields | all POST fields except website, captcha_*, copy_to_sender, vnmailer_*, h-captcha-response; field name = label; values without HTML, at most 2000 characters |
| Reply-To | field whose name looks like email, e-mail, email1 |
| Control fields | vnmailer_id, vnmailer_subject, vnmailer_copy_subject, vnmailer_copy_intro, vnmailer_hcaptcha_sitekey, captcha_answer, captcha_token, copy_to_sender, website (honeypot) |
| Response | AJAX (X-Requested-With or Accept: application/json): JSON; otherwise redirect back to the page (Referer) with vnmailer=success|error, vnmailer_msg, vnmailer_id |
| IP limit | 15 requests per 10 minutes |
Recipient list (from version 1.3.100). The handler compares the recipient (to, case-insensitive) with the list in assets/vn-formrender/recipients.php. The addresses of this list and always the own sender address from the SMTP configuration are allowed; it answers any other address with Dieser Empfänger ist für das Formular nicht freigegeben. The export writes the content of the list: it collects the addresses from data-recipient and from …native-form-handler.php?to=… in the HTML of all exported pages (the address may be URL-encoded) and creates recipients.php even if a page uses the handler without to (the list is then empty, only the sender address applies).
Export behavior#
If the export finds class="vn-formrender" or class="vn-sform-form" in any page, the following happens:
| Result | Path |
|---|---|
| Sending files | assets/vn-formrender/ (complete directory from vendor/vn-formrender: mailer.php, captcha.php, native-form-handler.php, render.js, PHPMailer) |
| Form JSONs | assets/vn-formrender/forms/*.json, plus forms/.htaccess with Options -Indexes |
| Recipient list | assets/vn-formrender/recipients.php (if addresses were found or a page uses native-form-handler.php) |
| hCaptcha secret | assets/vn-formrender/config.php (if set up) |
| Credentials | assets/vn-shared/config.php (if SMTP is set up) |
Script (vn-sform only) | vendor/vn-sform/vn-sform.js, included at the end of the page |
If SMTP is not set up, the export shows a notice; the form then responds with Formular ist noch nicht konfiguriert.
Forms with the VN Form Editor and the Form Renderer#
How it works together#
- In the VN Form Editor (tool, window with palette, canvas, properties, and the “Rules” and “Preview” tabs) you build the form by drag & drop.
- It is saved in the project as
assets/vn-formrender/forms/<name>.json. - A Form Renderer block (five designs) holds the name in the panel field
formFile; a script loadsrender.jsat runtime, which fetches the JSON (fetch), builds the form, evaluates rules and sends throughmailer.php.
The form 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" } ] }
]
}| File | Rule |
|---|---|
| Location | assets/vn-formrender/forms/<name>.json |
| Name | ^[a-zA-Z0-9_-]{1,60}$ (program and renderer filter out everything else) |
| Minimum content | an array fields; if rules is missing, [] applies |
| What is saved | { fields, rules }, indented, atomic (temporary file, then rename) |
Field properties#
| Property | Type | Meaning |
|---|---|---|
id | text (f1, f2 …) | Unique identifier; the target and conditions of rules refer to it |
type | text | see the next table |
label | text | Label (heading for heading, text for submit) |
placeholder | text | Placeholder for text/multi-line fields |
value | text | Value for hidden |
required | switch | Required field (consent is always required) |
hiddenByDefault | switch | Field starts invisible (only rules can show it) |
options | list | Entries for select, radio (default ["Option 1","Option 2"]) |
width | percent | Width (calc(<w>% - var(--vfr-gap))); default 100; heading, hcaptcha always 100 % |
linkText, linkUrl, linkSuffix | text | for consent: text, address, suffix (“gelesen und akzeptiere sie.”) |
hcaptchaSiteKey | text | for hcaptcha |
linkDisplayText, linkDisplayUrl | text | for linkdisplay |
Field types#
type | Description |
|---|---|
text, email, tel, url, number, date | Single-line input (input[type=…]); email is additionally used as Reply-To |
textarea | Multi-line text (optional character counter) |
select | Dropdown list from options |
radio | Option group from options |
checkbox | Single checkbox |
file | File upload (size maxFileSizeMB), sent along as an attachment |
hidden | Hidden field with value |
heading | Heading; in “multi-step” mode it starts a new page |
consent | Privacy checkbox with link (linkText, linkUrl, linkSuffix), always required |
copytosender | “Copy to me” (checkbox, acts like copy_to_sender) |
captcha | Math security question (as with vn-sform) |
hcaptcha | hCaptcha (see hCaptcha) |
signature | Signature (drawing area), sent along as an image (PNG) |
linkdisplay | Pure link display (no value) |
submit | Submit button |
Rules#
A rule watches fields and acts on a target field. Every change in the form re-evaluates all rules (engineApply): first the base state is restored (hiddenByDefault, required), then the rules whose condition is met take effect.
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" }
] }
] }| Property | Values | Meaning |
|---|---|---|
target | field id | Target field (not needed for redirect) |
action | see actions | What happens |
value | text | Value for setValue, address for redirect |
logic | AND (all), OR (any) | How the conditions of this level are combined |
conditions | list | Entries { field, op, value } or nested groups { logic, conditions } |
carryValues | switch, default on | For redirect: append all filled-in values as address parameters |
Operators#
op | Checks | Value needed |
|---|---|---|
equals / notEquals | text equal / not equal (exact) | yes |
contains / notContains | contains / does not contain (case-insensitive) | yes |
isEmpty / isNotEmpty | empty / not empty | no |
greaterThan / lessThan | number comparison | yes |
checked / notChecked | checkbox ticked / not ticked | no |
Radio and select compare the exact option text. A checkbox stores only on/off: use checked, not equals "ja". Condition sources are fields with a real value (text, textarea, email, tel, url, number, select, radio, checkbox, date, file, hidden, copytosender).
Actions#
action | Effect |
|---|---|
show | Show the target field |
hide | Hide the target field |
require | Make the target field required |
unrequire | Remove the requirement |
enable | Enable the target field |
disable | Disable the target field |
setValue | Set the value (triggers change) |
redirect | Redirect to the address in value (only once; values as parameters if carryValues) |
The Form Renderer block#
The block (vn-formrender, five designs: Standard, Background, Image frame, Photo card, Overlay) contains a hidden data element, an output field, an editor preview and a small start script.
Syntax (structure of the “Standard” block)
<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>| Part | Meaning |
|---|---|
section.vn-formrender | Detection in the export (copies vn-formrender/, writes recipients.php) |
.vnfr-data[data-…] | Settings for render.js (table below) |
.vnfr-out | render.js builds the form here |
.vnfr-builder-dummy | Static preview; visible in the editor (#canvas .vn-formrender .vnfr-builder-dummy {display:block}), replaced by render.js on the page |
data-vnfr-pending | The start script marks the section before it places render.js in the <head>; render.js looks for the waiting section |
data-vnfr-rendered | Set by render.js after the build |
The start script detects the editor with document.documentElement.classList.contains('is-builder'). The program never sets this class (see Editor detection); in the editor, therefore, the “live” branch of the start script runs. The editor preview (.vnfr-builder-dummy) stays visible through a rule in the canvas CSS.
Settings on .vnfr-data (names in lowercase; truth values true/on/1; a value that still contains {{ counts as empty):
| Attribute | Default | Meaning |
|---|---|---|
data-formfile | — | Name of the JSON (without path and extension; only [a-zA-Z0-9_-]) |
data-recipient | — | Recipient |
data-subject | Neue Nachricht über die Webseite | Subject |
data-copytosender | off | Copy to the sender as default |
data-thankyouurl | empty | Thank-you page |
data-style | standard | Design |
data-cardwidth, data-cardopacity, data-cardbg | 45, 100, #ffffff | Card (photo card/overlay) |
data-overlaybtn | Kontakt aufnehmen | Button text of the overlay design |
data-inputstyle | boxed | boxed or underline |
data-inputbg, data-inputbgopacity | #ffffff, 100 | Field background |
data-customfont | empty | Google font name; loads the font from fonts.googleapis.com |
data-twocolumns | off | Automatic 2-column layout |
data-mobilekeepwidth | off | Keep own field width on phones |
data-borderless, data-stickyform, data-compactmode, data-syncradius | off | Borderless, fixed, compact, radii linked |
data-shadowlevel | soft | none, soft, medium, strong |
data-showfieldicons | off | Icons before the labels |
data-maxfilesizemb | 3 | File limit in the browser (MB; 1–8 in the panel) |
data-captchatransparent | off | Captcha box without background |
data-livevalidation | off | Live validation with check marks |
data-charcounter | off | Character counter for textarea |
data-showprogressbar | off | Progress bar with several headings |
data-multistep, data-multistepnexttext, data-multistepbacktext | off, Weiter, Zurück | Multi-step (headings = pages) |
data-hcaptchasize, data-hcaptchatheme | normal, light | normal/compact; light/dark |
data-submiticon | none | arrow, check, paperplane |
data-successanimation | off | Success animation |
data-backgroundfullblock | off | Background across the whole block (class vnfr-background-fullblock) |
Saving and embedding#
| Step | Place |
|---|---|
| Saving | In the form editor: name field, “Save”; list of saved forms to open, New, Delete; “Unsaved” indicator |
| Exchange | JSON import and download (to take along into another project) |
| Embedding | Insert the block “VN Form Renderer”; in the panel under “Form configuration” enter the file name (the field offers the saved names as a selection list, free input possible) |
| Recipient | Panel field recipientEmail; subject emailSubject; thank-you page thankYouUrl |
| Static instead of dynamic | Block “Form (static)” in the “Custom code” tab (see sform-from-editor) |
On export it is enough to place the block on a page: the program takes forms/<name>.json along and generates recipients.php.
Security notes#
| Topic | Measure |
|---|---|
| Output | mailer.php escapes all values (htmlspecialchars), line breaks in the subject are removed |
| Recipient | Only addresses from recipients.php (mailer.php; native-form-handler.php likewise from version 1.3.100, there additionally the own sender address); one address per form |
| Spam | Honeypot, IP limit (5 per 10 minutes), optionally math captcha (signed token) or hCaptcha |
| Size | 40 fields, 8000 characters, 8/15 MB attachments |
| Credentials | Deliver config.php with the SMTP password only through PHP; never keep the password in the project folder |
| File uploads | are not stored, only attached; the mail provider checks attachments |
| Required fields | checked only in the browser, not on the server |
| Open relay | from version 1.3.100 native-form-handler.php checks against recipients.php; without this file (export with an older version) it sends to any address. Export and upload old pages again |
| Third parties | data-customfont (Google Fonts) and hCaptcha load without consent |