Zum Hauptinhalt springen
Mit dem $wsForm-Modul arbeiten Sie im Frontend mit Formularen. Sie laden die Struktur eines Formulars (Felder, Labels, Validierungen), um es auszugeben, und lesen nach dem Absenden die übermittelten Daten. Auf dieser Seite geht es um das Laden und Lesen von Formulardaten. Das Absenden selbst (und weitere Formular-Aktionen) ist unter Aktionen → Inquiry dokumentiert; die Formulare werden in der inquiry-Konfiguration angelegt.

​
Grundkonzept

Ein Formular durchläuft vier Schritte, die $wsForm zusammen mit der InquirySend-Aktion abbildet:
  1. Struktur laden – loadType(formId) liefert die Felder eines Formulars (z. B. "contact"), damit Sie es im Frontend ausgeben können.
  2. Absenden – der Kunde sendet das Formular über die Aktion InquirySend ($wsActions). Das Formular schickt das versteckte Feld formId mit dem Formularnamen mit. Die Formularfelder werden mit dem Präfix form. benannt (z. B. form.subject).
  3. Anfrage-ID erhalten – nach erfolgreichem Absenden liegt die Anfrage-ID vor (in InquirySend.successInfo.inquiryId, ebenso in $wsForm.inquiryId).
  4. Daten lesen – load(inquiryId) liefert die übermittelten Daten zur Anfrage-ID, z. B. für eine Bestätigungsanzeige.
Zusätzlich listet loadAllTypes() alle Formulartypen des Shops auf.

​
Modulübersicht

Beispiel / Ausschnitt über $wsForm 
{{= $wsForm | json }}
JSON-Ausgabe 
{
  "inquiryId": "...",
  "load": "ƒ()",
  "loadAllTypes": "ƒ()",
  "loadType": "ƒ()"
}
Anmerkung: "ƒ()" kennzeichnet eine Funktion. Variablen in der Übersicht
VariableTypBeschreibung
inquiryIdstringAnfrage-ID nach erfolgreichem Absenden eines Formulars.
Methoden in der Übersicht
MethodeRückgabe-TypBeschreibung
loadType()mapLädt die Struktur eines Formulars anhand des Formularnamens.
loadAllTypes()arrayLädt alle verfügbaren Formulartypen des Shops.
load()mapLädt die übermittelten Daten einer abgeschickten Anfrage.

​
Templates

Formulare werden überall im Shop verwendet, beispielsweise im Kontaktformular, beim Widerrufsformular oder bei der Passwort-Wiederherstellung.

​
Variablen

​
$wsForm.inquiryId

Enthält die eindeutige Anfrage-ID nach dem erfolgreichen Absenden eines Formulars. Mit dieser ID rufen Sie die übermittelten Daten über load() ab. 
Anfrage-ID: {{= $wsForm.inquiryId }}

​
Methoden

​
$wsForm.loadType()

Lädt die Struktur eines Formulars (Felder, Labels, Validierungen) anhand des Formularnamens. Nutzen Sie die zurückgegebenen Felder, um das Formular zu rendern. Signatur
$wsForm.loadType(formId) Rückgabe
map mit den Formular-Eigenschaften: name (Formularname), fields (Feldliste), email (E-Mail-Konfiguration des Formulars) und loadField (Methode zum Laden eines einzelnen Feldes). Parameter
NameTypPflichtBeschreibung
formIdstringjaName des Formulars (z. B. "contact").
{{ foreach $field in $wsForm.loadType("contact").fields }}
  {{= $field.label }} ({{= $field.name }}){{ if $field.required }} *{{ /if }}
{{ /foreach }}

​
Eigenschaften eines Feld-Objekts

Ist dem Formular ein RuleSet zugewiesen, werden label, required, visible und defaultValue automatisch durch dessen Regeln angepasst.
EigenschaftRückgabe-TypBeschreibung
namestringTechnischer Feldname.
labelstringAnzeigename des Feldes.
requiredboolPflichtfeldkennzeichen.
validationsarrayValidierungsregeln des Feldes (je type und name).
defaultValuestringStandardwert; zum Vorbelegen, wenn der Wert leer ist.
valuestringAktueller Wert (wird bei der Aktion inquiryCheck befüllt).
visibleboolOb das Feld angezeigt werden soll.

​
$wsForm.loadAllTypes()

Lädt alle verfügbaren Formulartypen des Shops. Signatur
$wsForm.loadAllTypes() Rückgabe
array – Liste aller Formulartypen. 
{{ foreach $formType in $wsForm.loadAllTypes() }}
  Formular: {{= $formType.name }}
{{ /foreach }}

​
$wsForm.load()

Lädt die übermittelten Daten einer abgeschickten Formularanfrage. Übergeben Sie die Anfrage-ID, die Sie nach dem Absenden erhalten haben. Signatur
$wsForm.load(inquiryId) Rückgabe
map – die Anfragedaten (Struktur siehe unten). Parameter
NameTypPflichtBeschreibung
inquiryIdstringjaID der abgeschickten Anfrage.

​
Struktur der Anfragedaten

EigenschaftRückgabe-TypBeschreibung
idstringEindeutige ID der Anfrage.
formIdstringName des verwendeten Formulars.
createdAtstringZeitpunkt des Absendens (ISO 8601, UTC).
submittermapDaten des Absenders (email, sessionId, ipAddress).
formmapEingegebene Felddaten, je Feld { label, value }.
Auf ein einzelnes Feld greifen Sie über seinen technischen Namen zu, z. B. form.firstName.value und form.firstName.label.

​
Aktionen

Aktionen zu diesem Modul (Absenden, Prüfen) sind separat dokumentiert: Aktionen → Inquiry.

​
Beispiele

​
Formularfelder rendern

loadType() liefert die Felder eines Formulars, aus denen Sie die Eingabefelder erstellen. Die Feldnamen erhalten das Präfix form.. Ausgeblendete Felder (visible = false) überspringen Sie und Pflichtfelder kennzeichnen Sie mit required. 
{{ foreach $field in $wsForm.loadType("contact").fields }}
  {{ if $field.visible }}
    <label>
      {{= $field.label }}{{ if $field.required }} *{{ /if }}
      <input type="text" name="form.{{= $field.name }}" value="{{= $field.defaultValue }}">
    </label>
  {{ /if }}
{{ /foreach }}
Ergebnis
Für jedes sichtbare Feld des Kontaktformulars gibt es ein beschriftetes Eingabefeld mit dem Präfix form-. Pflichtfelder sind mit einem Sternchen (*) markiert. Das Absenderfeld email ist kein loadType-Feld und wird separat als input name="email" ergänzt.

​
Vollständiges Kontaktformular mit Absenden und Bestätigung

Dieses Beispiel zeigt den kompletten Loop: Formular mit den nötigen versteckten Feldern und form.-Präfix rendern, bei Fehler die Eingaben erhalten und Feldfehler anzeigen, bei Erfolg die Daten über load() lesen. 
{{ var $action = $wsActions.create("InquirySend") }}

<form method="post" action="{{= $wsViews.current.url() }}">
  <input type="hidden" name="wscsrf" value="{{= $action.csrf }}">
  <input type="hidden" name="wsact" value="{{= $action.id }}">
  <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">
  <input type="hidden" name="formId" value="contact">

  {{ if $action.success }}
    {{ var $inquiry = $wsForm.load($action.successInfo.inquiryId) }}
    <p>Danke für Ihre Anfrage (ID {{= $inquiry.id }}).</p>
    <p>Bestätigung an: {{= $inquiry.submitter.email }}</p>
  {{ else }}
    <input type="email" name="email" placeholder="E-Mail"
           value="{{= $action.params.email | ifNull('') }}">

    <input type="text" name="form.subject" placeholder="Betreff"
           value="{{= $action.params.form.subject | ifNull('') }}">
    {{ if $action.errorsByField.subject }}
      <span class="error">{{= $action.errorsByField.subject[0].text }}</span>
    {{ /if }}

    <textarea name="form.comment" placeholder="Ihre Nachricht">{{= $action.params.form.comment | ifNull('') }}</textarea>
    {{ if $action.errorsByField.comment }}
      <span class="error">{{= $action.errorsByField.comment[0].text }}</span>
    {{ /if }}

    <button type="submit">Absenden</button>
  {{ /if }}
</form>
Ergebnis
Das Formular erscheint vor dem Absenden. Bei fehlerhafter Eingabe bleiben die Werte erhalten und die Feldfehler werden angezeigt. Nach erfolgreichem Absenden erscheint die Bestätigung mit der Anfrage-ID.
Nutzt das Formular ein Captcha (z. B. reCAPTCHA v3), gehört es hinter {{ if $wsConsent.checkAllowed("recaptchav3") }} und braucht ein Feld <input type="hidden" name="wscaptchatoken"> sowie die Captcha-Komponente. Siehe $wsConsent.
Beispiel einer von load() zurückgegebenen Struktur (Felder gemäß dem echten Kontaktformular; die load()-Struktur selbst ist noch zu bestätigen): 
{
  "id": "52ad06427c68738c",
  "formId": "contact",
  "createdAt": "2025-04-14T06:43:57Z",
  "submitter": {
    "email": "kundin@beispiel.de",
    "ipAddress": "95.90.217.XXX",
    "sessionId": "c5a37018627bf18e…"
  },
  "form": {
    "subject": { "label": "Betreff", "value": "Test-Anfrage" },
    "comment": { "label": "Ihre Nachricht", "value": "Bitte um weitere Infos" }
  }
}