$wsForm - Formulare - WEBSALE Dokumentation

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:

Struktur laden – loadType(formId) liefert die Felder eines Formulars (z. B. "contact"), damit Sie es im Frontend ausgeben können.
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).
Anfrage-ID erhalten – nach erfolgreichem Absenden liegt die Anfrage-ID vor (in InquirySend.successInfo.inquiryId, ebenso in $wsForm.inquiryId).
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

Variable	Typ	Beschreibung
`inquiryId`	string	Anfrage-ID nach erfolgreichem Absenden eines Formulars.

Methoden in der Übersicht

Methode	Rückgabe-Typ	Beschreibung
`loadType()`	map	Lädt die Struktur eines Formulars anhand des Formularnamens.
`loadAllTypes()`	array	Lädt alle verfügbaren Formulartypen des Shops.
`load()`	map	Lä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
Rückgabe
map mit den Formular-Eigenschaften: name (Formularname), fields (Feldliste), email (E-Mail-Konfiguration des Formulars), loadField (Methode zum Laden eines einzelnen Feldes) und nodeId (ID des Konfigurationsknotens, als zweiter Parameter für $wsOptions.get(name, nodeId)). Parameter

Name	Typ	Pflicht	Beschreibung
`formId`	string	ja	Name 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.

Eigenschaft	Rückgabe-Typ	Beschreibung
`name`	string	Technischer Feldname.
`label`	string	Anzeigename des Feldes.
`required`	bool	Pflichtfeldkennzeichen.
`validations`	array	Validierungsregeln des Feldes (je `type` und `name`).
`defaultValue`	string	Standardwert; zum Vorbelegen, wenn der Wert leer ist.
`value`	string	Aktueller Wert (wird bei der Aktion `inquiryCheck` befüllt).
`visible`	bool	Ob 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

Name	Typ	Pflicht	Beschreibung
`inquiryId`	string	ja	ID der abgeschickten Anfrage.

Struktur der Anfragedaten

Eigenschaft	Rückgabe-Typ	Beschreibung
`id`	string	Eindeutige ID der Anfrage.
`formId`	string	Name des verwendeten Formulars.
`createdAt`	string	Zeitpunkt des Absendens (ISO 8601, UTC).
`submitter`	map	Daten des Absenders (`email`, `sessionId`, `ipAddress`).
`form`	map	Eingegebene 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" }
  }
}

Weiterführende Links

Aktionen → Inquiry – das Absenden und Prüfen von Formularen (InquirySend, inquiryCheck).
inquiry - Formulare – legt die Formulare und Felder an, inkl. RuleSet.
actions - Formulare – Konfiguration der Formular-Aktionen.

Frontend

Die Basics

Getting Started

Referenz – Aktionen

Referenz – Sprache

Referenz – Module

Integrationsanleitung

Praxisbeispiele

$wsForm - Formulare

Grundkonzept

Modulübersicht

Templates

Variablen

$wsForm.inquiryId

Methoden

$wsForm.loadType()

Eigenschaften eines Feld-Objekts

$wsForm.loadAllTypes()

$wsForm.load()

Struktur der Anfragedaten

Aktionen

Beispiele

Formularfelder rendern

Vollständiges Kontaktformular mit Absenden und Bestätigung

Weiterführende Links

​Grundkonzept

​Modulübersicht

​Templates

​Variablen

​$wsForm.inquiryId

​Methoden

​$wsForm.loadType()

​Eigenschaften eines Feld-Objekts

​$wsForm.loadAllTypes()

​$wsForm.load()

​Struktur der Anfragedaten

​Aktionen

​Beispiele

​Formularfelder rendern

​Vollständiges Kontaktformular mit Absenden und Bestätigung

​Weiterführende Links

Grundkonzept

Modulübersicht

Templates

Variablen

$wsForm.inquiryId

Methoden

$wsForm.loadType()

Eigenschaften eines Feld-Objekts

$wsForm.loadAllTypes()

$wsForm.load()

Struktur der Anfragedaten

Aktionen

Beispiele

Formularfelder rendern

Vollständiges Kontaktformular mit Absenden und Bestätigung

Weiterführende Links