VN-Designer Developer Documentation
08

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.

WayWhere the form livesWhen 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 browserForms 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

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>

(from src/vn-sform.js; themes/vn-handwerk-src/components/kontakt1 and gallery-content/vn-app-theme/src/components/signup1 use the same form)

PartRequiredPurpose
form.vn-sform-formyesIdentifying 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 fieldOne field with its label; data-type determines how it is evaluated
.vn-sform-labelyesLabel; its text becomes the name of the field in the mail
div.vn-sform-hp with input[name="website"]yesHoneypot (spam trap), see Spam protection
button.vn-sform-enterrecommendedInvisible submit button so that Enter in a field submits
div.vn-sform-statusyesMessage area (hidden), see Messages
a[data-vn-sform-submit]yesThe submit button
novalidateyesThe script does the validation (own error messages below the fields)

The form element: data attributes#

AttributeType/valuesDefaultMeaning
data-recipientemail address—Recipient; exactly one address (see Recipients)
data-subjecttextNeue Nachricht über die WebseiteSubject of the mail (at most 150 characters, line breaks removed)
data-successtextDanke für deine Nachricht! (with lang="en": Thank you for your message!)Message after a successful submit
data-thankyouaddressemptyThank-you page: if set, the visitor is redirected there instead of the message being shown
data-mailerpathassets/vn-formrender/mailer.phpAddress of the sending script, relative to the page; captcha.php is derived from it (mailer.php… → captcha.php)
data-vn-sform-ready1—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-typeInput elementValue in the mail
text, tel, url, number, dateinput.vn-sform-input[type=…]entered text (trimmed)
emailinput[type=email]text; the first valid email address becomes the Reply-To and the target of the sender copy
textareatextarea.vn-sform-input.vn-sform-textareatext
selectselect.vn-sform-input.vn-sform-selectselected value
radiodiv.vn-sform-choices with several input[type=radio] (same name)selected value; required if the first radio has required
checkboxinput[type=checkbox]Ja or Nein (yes or no)
consentinput[type=checkbox][required] (privacy)Ja/Nein; always required
copytosenderinput[type=checkbox][data-vn-copytosender]not in the mail; switches on the copy to the sender
fileinput.vn-sform-file[type=file]file as an attachment; name and size in the mail
captchasee Security questionnot in the mail
headingh3.vn-sform-heading (the field is called vn-sform-field vn-sform-heading-wrap)is skipped
submita.btn.vn-sform-submit[data-vn-sform-submit]is skipped
(no field) input[type=hidden]name, value, data-labelentry under data-label (otherwise name) if a value is present

Examples (from 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>

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.

ValueRangeMeaning
style="--span:N"1–12Number of columns; 6 = half width, 12 = full row
from the form editorwidth 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 emptyBitte ausfüllen. (Please fill in.)
Email field with an invalid addressBitte eine gültige E-Mail-Adresse eingeben. (Please enter a valid email address.)
Required checkbox not tickedBitte bestätigen. (Please confirm.)
Radio group without a choice (first radio required)Bitte auswählen. (Please choose.)
Required file missingBitte eine Datei wählen. (Please choose a file.)
File larger than 3 MBDie Datei ist zu groß (max. 3 MB). (The file is too large.)
Math field emptyBitte 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

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>
AttributeMeaning
data-vn-sform-submitA click submits the form (preventDefault); the script sets vn-sform-busy on the button (no double click)
a.btnThe button is a normal button editable by click (color, label, icon; see Buttons)
.vn-sform-enterAdditional 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).

ProtectionWhereDescription
Honeypot websiteForm + serverNot empty = silent fake success
Math security questionField type captchaOnly if the form contains the field
IP limitServerat 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 limitServerat most 40 fields, 8000 characters in total (names + values)
Recipient listServeronly addresses from recipients.php (Recipients)

Math security question#

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>
AttributeMeaning
data-vn-captcha-qThe script writes the math question here (a + b = ?, numbers 1–9)
data-vn-captcha-answerThe answer field
data-vn-captcha-tokenHidden 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#

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

LimitValueWhere
Size per file in the browser3 MBvn-sform.js (message when choosing)
Size per file on the server8 MBmailer.php (Datei zu groß (max. 8 MB).)
All attachments together15 MBmailer.php
Typesno restrictionThe 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):

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)KindMeaning
recipienttextRecipient (into data-recipient)
subjecttextSubject (data-subject)
successTexttextSuccess message (data-success)
thankYouUrltextThank-you page (data-thankyou)
padding, maxWidth, align, gapnumbers/choiceSpacing, maximum width, alignment, field gap
fieldStyleoutline, filled, lineAppearance of the fields
radius, fieldSizenumber, sm/md/lgRounding, size
borderColor, fieldBg, focusColorcolorBorder, background, focus
bgColor, labelColor, textColor, errorColor, okColorcolorSurface and text colors
btnAlignleft, center, right, fullAlignment 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:

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>

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.

GroupField types
Taken overtext, 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 &#123;&#123; 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 }.

StepCheckResponse on violation
1Method must be POSTUngültige Anfrage-Methode.
2../vn-shared/config.php must exist and contain $hmac_secret, $smtp_host, $smtp_username, $smtp_passwordFormular ist noch nicht konfiguriert …
3Read the content (JSON or multipart)Ungültige Anfrage.
4Honeypot website not emptySuccess is faked, nothing is sent
5hCaptcha or math captcha (depending on what was sent)Sicherheitsabfrage … / hCaptcha-Prüfung fehlgeschlagen …
6IP limit: 5 requests per 10 minutes (file in sys_get_temp_dir())Zu viele Anfragen, bitte später erneut versuchen.
7recipient must be a valid single email addressKein gültiger Empfänger konfiguriert.
8Address must be in recipients.php (if the file exists)Dieser Empfänger ist für das Formular nicht freigegeben.
9There must be fields or files; at most 40 fields, 8000 charactersKeine Formulardaten übermittelt. / Eingabe zu lang.
10Files: 8 MB per file, 15 MB in total, real uploads onlyDatei zu groß … / Anhänge zusammen zu groß …
11Subject: at most 150 characters, \r/\n removed (header injection)—
12Mail: HTML table (field name, value; values with htmlspecialchars and nl2br) and a text version; Reply-To only with a valid addressMail konnte nicht versendet werden, bitte später erneut versuchen.
13Optional copy to the senderErrors 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
<?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',
);
RuleDescription
Contentall data-recipient values of all exported pages and, from version 1.3.100, all addresses from …native-form-handler.php?to=…, in lowercase
Charactersonly harmless addresses (at most 254 characters, without quotation marks, backslash, $, spaces); they are stored as simple PHP strings
Who checksmailer.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 formnot 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
<?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 = "…";
VariableMeaning
$smtp_host, $smtp_portServer, port (default 587)
$smtp_encryptiontls (STARTTLS), ssl (SMTPS), otherwise none
$smtp_username, $smtp_passwordLogin (required)
$smtp_from_email, $smtp_from_nameSender of the mails
$hmac_secretSecret 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:

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

FeatureBehavior
Callnative-form-handler.php?to=name@example.com as action
Recipientto 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)
Fieldsall POST fields except website, captcha_*, copy_to_sender, vnmailer_*, h-captcha-response; field name = label; values without HTML, at most 2000 characters
Reply-Tofield whose name looks like email, e-mail, email1
Control fieldsvnmailer_id, vnmailer_subject, vnmailer_copy_subject, vnmailer_copy_intro, vnmailer_hcaptcha_sitekey, captcha_answer, captcha_token, copy_to_sender, website (honeypot)
ResponseAJAX (X-Requested-With or Accept: application/json): JSON; otherwise redirect back to the page (Referer) with vnmailer=success|error, vnmailer_msg, vnmailer_id
IP limit15 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:

ResultPath
Sending filesassets/vn-formrender/ (complete directory from vendor/vn-formrender: mailer.php, captcha.php, native-form-handler.php, render.js, PHPMailer)
Form JSONsassets/vn-formrender/forms/*.json, plus forms/.htaccess with Options -Indexes
Recipient listassets/vn-formrender/recipients.php (if addresses were found or a page uses native-form-handler.php)
hCaptcha secretassets/vn-formrender/config.php (if set up)
Credentialsassets/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#

  1. In the VN Form Editor (tool, window with palette, canvas, properties, and the “Rules” and “Preview” tabs) you build the form by drag & drop.
  2. It is saved in the project as assets/vn-formrender/forms/<name>.json.
  3. A Form Renderer block (five designs) holds the name in the panel field formFile; a script loads render.js at runtime, which fetches the JSON (fetch), builds the form, evaluates rules and sends through mailer.php.

The form 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" } ] }
  ]
}
FileRule
Locationassets/vn-formrender/forms/<name>.json
Name^[a-zA-Z0-9_-]{1,60}$ (program and renderer filter out everything else)
Minimum contentan array fields; if rules is missing, [] applies
What is saved{ fields, rules }, indented, atomic (temporary file, then rename)

Field properties#

PropertyTypeMeaning
idtext (f1, f2 …)Unique identifier; the target and conditions of rules refer to it
typetextsee the next table
labeltextLabel (heading for heading, text for submit)
placeholdertextPlaceholder for text/multi-line fields
valuetextValue for hidden
requiredswitchRequired field (consent is always required)
hiddenByDefaultswitchField starts invisible (only rules can show it)
optionslistEntries for select, radio (default ["Option 1","Option 2"])
widthpercentWidth (calc(<w>% - var(--vfr-gap))); default 100; heading, hcaptcha always 100 %
linkText, linkUrl, linkSuffixtextfor consent: text, address, suffix (“gelesen und akzeptiere sie.”)
hcaptchaSiteKeytextfor hcaptcha
linkDisplayText, linkDisplayUrltextfor linkdisplay

Field types#

typeDescription
text, email, tel, url, number, dateSingle-line input (input[type=…]); email is additionally used as Reply-To
textareaMulti-line text (optional character counter)
selectDropdown list from options
radioOption group from options
checkboxSingle checkbox
fileFile upload (size maxFileSizeMB), sent along as an attachment
hiddenHidden field with value
headingHeading; in “multi-step” mode it starts a new page
consentPrivacy checkbox with link (linkText, linkUrl, linkSuffix), always required
copytosender“Copy to me” (checkbox, acts like copy_to_sender)
captchaMath security question (as with vn-sform)
hcaptchahCaptcha (see hCaptcha)
signatureSignature (drawing area), sent along as an image (PNG)
linkdisplayPure link display (no value)
submitSubmit 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

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" }
    ] }
  ] }
PropertyValuesMeaning
targetfield idTarget field (not needed for redirect)
actionsee actionsWhat happens
valuetextValue for setValue, address for redirect
logicAND (all), OR (any)How the conditions of this level are combined
conditionslistEntries { field, op, value } or nested groups { logic, conditions }
carryValuesswitch, default onFor redirect: append all filled-in values as address parameters

Operators#

opChecksValue needed
equals / notEqualstext equal / not equal (exact)yes
contains / notContainscontains / does not contain (case-insensitive)yes
isEmpty / isNotEmptyempty / not emptyno
greaterThan / lessThannumber comparisonyes
checked / notCheckedcheckbox ticked / not tickedno

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#

actionEffect
showShow the target field
hideHide the target field
requireMake the target field required
unrequireRemove the requirement
enableEnable the target field
disableDisable the target field
setValueSet the value (triggers change)
redirectRedirect 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)

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>
PartMeaning
section.vn-formrenderDetection in the export (copies vn-formrender/, writes recipients.php)
.vnfr-data[data-…]Settings for render.js (table below)
.vnfr-outrender.js builds the form here
.vnfr-builder-dummyStatic preview; visible in the editor (#canvas .vn-formrender .vnfr-builder-dummy {display:block}), replaced by render.js on the page
data-vnfr-pendingThe start script marks the section before it places render.js in the <head>; render.js looks for the waiting section
data-vnfr-renderedSet 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):

AttributeDefaultMeaning
data-formfile—Name of the JSON (without path and extension; only [a-zA-Z0-9_-])
data-recipient—Recipient
data-subjectNeue Nachricht über die WebseiteSubject
data-copytosenderoffCopy to the sender as default
data-thankyouurlemptyThank-you page
data-stylestandardDesign
data-cardwidth, data-cardopacity, data-cardbg45, 100, #ffffffCard (photo card/overlay)
data-overlaybtnKontakt aufnehmenButton text of the overlay design
data-inputstyleboxedboxed or underline
data-inputbg, data-inputbgopacity#ffffff, 100Field background
data-customfontemptyGoogle font name; loads the font from fonts.googleapis.com
data-twocolumnsoffAutomatic 2-column layout
data-mobilekeepwidthoffKeep own field width on phones
data-borderless, data-stickyform, data-compactmode, data-syncradiusoffBorderless, fixed, compact, radii linked
data-shadowlevelsoftnone, soft, medium, strong
data-showfieldiconsoffIcons before the labels
data-maxfilesizemb3File limit in the browser (MB; 1–8 in the panel)
data-captchatransparentoffCaptcha box without background
data-livevalidationoffLive validation with check marks
data-charcounteroffCharacter counter for textarea
data-showprogressbaroffProgress bar with several headings
data-multistep, data-multistepnexttext, data-multistepbacktextoff, Weiter, ZurückMulti-step (headings = pages)
data-hcaptchasize, data-hcaptchathemenormal, lightnormal/compact; light/dark
data-submiticonnonearrow, check, paperplane
data-successanimationoffSuccess animation
data-backgroundfullblockoffBackground across the whole block (class vnfr-background-fullblock)

Saving and embedding#

StepPlace
SavingIn the form editor: name field, “Save”; list of saved forms to open, New, Delete; “Unsaved” indicator
ExchangeJSON import and download (to take along into another project)
EmbeddingInsert 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)
RecipientPanel field recipientEmail; subject emailSubject; thank-you page thankYouUrl
Static instead of dynamicBlock “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#

TopicMeasure
Outputmailer.php escapes all values (htmlspecialchars), line breaks in the subject are removed
RecipientOnly 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
SpamHoneypot, IP limit (5 per 10 minutes), optionally math captcha (signed token) or hCaptcha
Size40 fields, 8000 characters, 8/15 MB attachments
CredentialsDeliver config.php with the SMTP password only through PHP; never keep the password in the project folder
File uploadsare not stored, only attached; the mail provider checks attachments
Required fieldschecked only in the browser, not on the server
Open relayfrom 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 partiesdata-customfont (Google Fonts) and hCaptcha load without consent