Formulare

Zuletzt aktualisiert: September 2026, Plugin 1.5.2

Ein Formular ist eine geordnete Liste typisierter Felder, die auf die Spalten einer Dataverse-Tabelle abgebildet sind. Einsendungen werden auf dem Server validiert und konvertiert und legen einen Datensatz an oder aktualisieren im Update-Modus den Datensatz der aufgerufenen Seite. Jeder Schreibvorgang wird per Nonce geprüft, über ein Honeypot-Feld abgesichert und durch ein Rate Limit begrenzt; Cloudflare Turnstile lässt sich je Formular einschalten.

Ein Formular einrichten

Auf dem Tab "Forms" braucht ein Formular einen Key, das Entity Set und mindestens ein Feld; der logische Name der Tabelle ist optional, wird aber für Beschriftungen aus den Metadaten, Auswahloptionen und Pflichtstufen benötigt. Die Felder stehen in der Feldtabelle: eine Zeile je Eingabefeld, in Anzeigereihenfolge.

Unter der Tabelle: Mode, Bind to collection, Success message, Redirect after success und die Turnstile-Einstellungen. Die ältere Textarea "Field map" und die Zeile "Required fields" funktionieren für einfache Textformulare weiterhin; Zeilen in der Feldtabelle haben Vorrang. "Consent" fügt eine Checkbox hinzu, die der Besucher anhaken muss. "Relate to" verknüpft einen angelegten Datensatz mit dem Datensatz, auf dem das Formular angezeigt wurde: Geben Sie die Navigationseigenschaft des Lookups (Schreibweise des Schemanamens, zum Beispiel wbs_Listing) und den Key der Collection an.

Platzieren Sie das Formular mit [wbsdvc_form name="inquiry"], dem Block "Dataverse Form" oder dem Attribut form eines Collection- oder Record-Shortcodes, das es unter der Detailansicht anhängt.

Feldtypen

Typisierungsregeln

• Auswahlfelder werden zuerst über den Optionswert aufgelöst, dann über einen Abgleich der Beschriftung ohne Beachtung der Groß- und Kleinschreibung. Die Optionen stammen aus dem Options-Text der Zeile oder, wenn dieser leer ist, aus den Spaltenmetadaten. Ein Wert außerhalb der bekannten Optionen wird mit einer Meldung abgewiesen, die das Feld benennt.
• Datumswerte werden als YYYY-MM-DD gespeichert. Datum-und-Zeit-Werte ohne Offset werden in der Zeitzone der Website gelesen und in UTC geschrieben; die Vorbelegung rechnet zurück.
• Lookups akzeptieren eine GUID oder einen Namen. Ein Name wird mit einer einzigen Abfrage gegen die name_column des Ziels aufgelöst; kein Treffer ist ein Validierungsfehler. nav ist standardmäßig der logische Name der Spalte; setzen Sie es, wenn die Navigationseigenschaft in der Groß- und Kleinschreibung abweicht.
• Metadaten füllen Beschriftungen, Optionen und Pflichtkennzeichen, die ein Admin leer gelassen hat. Sind die Metadaten nicht verfügbar, wird das Formular trotzdem mit dem gerendert, was die Zeilen vorgeben.
• Leere optionale Felder werden beim Anlegen übersprungen. Pflichtfelder, auch die von Dataverse als erforderlich markierten, blockieren die Einsendung mit einer Meldung für den Besucher.

Update-Modus und bind_to

Setzen Sie Mode auf update und wählen Sie unter Bind to collection eine Collection über demselben Entity Set. Das Formular belegt seine Eingabefelder dann aus dem Datensatz vor, der über ?dvc=<slug> ausgewählt wurde (oder aus dem Datensatz, an den es angehängt ist), und speichert Änderungen mit einem PATCH unter If-Match: *, sodass es nie versehentlich einen Datensatz anlegt. Der Datensatz muss über die gebundene Collection sichtbar sein, einschließlich ihres Statusfilters; eine geratene ID eines verborgenen Datensatzes wird abgewiesen. Im Update-Modus leert ein geleertes Text-, Zahlen-, Datums- oder Auswahlfeld seine Spalte; Lookups, Ja/Nein-Felder und versteckte Felder bleiben unangetastet. Ist Bind to leer, greift die Collection aus Relate to. Der Anwendungsbenutzer braucht die Berechtigung Write auf die Tabelle, und jeder Besucher, der den Datensatz sehen kann, kann die zugeordneten Spalten bearbeiten. Binden Sie Update-Formulare deshalb an Collections mit einem engen Statusfilter oder nutzen Sie die Zugriffsregeln des Business-Tarifs.

Erfolgsmeldung und Weiterleitung

Die Success message ersetzt den Standard-Dankestext. Redirect after success leitet den Besucher stattdessen auf eine Seite desselben Hosts weiter; andere Hosts werden ignoriert. Die Antworten enthalten die ID des neuen Datensatzes, die auch die Actions wbs_dataverse_connect_record_created und wbs_dataverse_connect_record_updated sowie der Webhook form.created erhalten.

Cloudflare Turnstile

1. Legen Sie im Cloudflare-Dashboard ein Turnstile-Widget für Ihre Domain an und kopieren Sie Site Key und Secret Key.
2. Tragen Sie beide Schlüssel im Formulareditor ein. Sie werden einmal, websiteweit, gespeichert und von allen Formularen gemeinsam genutzt; das Secret wird danach nicht mehr angezeigt.
3. Haken Sie "Require a Turnstile challenge on this form" bei jedem Formular an, das Turnstile nutzen soll.

Ein Formular mit dieser Option lädt das Widget-Skript im Browser von challenges.cloudflare.com, und beim Absenden prüft Ihre Website den Token zusammen mit der IP-Adresse des Besuchers über den siteverify-Endpunkt von Cloudflare. Ohne beide Schlüssel wird die Challenge übersprungen. Formulare ohne diese Option kontaktieren Cloudflare nie.

Einwilligung und Spam-Schutz

• REST-Nonce bei jeder Einsendung (X-WP-Nonce); der Endpunkt ist bewusst öffentlich und weist Anfragen ohne Nonce ab.
• Honeypot-Feld _dvc_website: Bots füllen es aus, Menschen sehen es nie, und die Antwort ist ein stiller Erfolg.
• Rate Limit: 5 Einsendungen je IP-Adresse in 10 Minuten.
• Optional Turnstile je Formular sowie die optionale Einwilligungs-Checkbox.

Werte werden beim Eingang bereinigt und beim Ausgang typisiert; nichts erreicht die Web API unvalidiert. Fehlgeschlagene Schreibvorgänge werden mit dem Dataverse-Detail für den Admin protokolliert und lösen einen Health Alert aus; der Besucher sieht eine allgemeine Meldung.

Die WBS-Forms-Bridge

Das kostenlose Plugin nimmt auch Einsendungen von WBS Forms entgegen (oder von jedem Formular-Builder, der wbs_forms_after_submit mit einem Array aus Feldname und Wert auslöst). Das Formular rendert, validiert und versendet weiterhin selbst; die Bridge bildet die Felder mit Typisierung je Feld auf eine Tabelle ab und legt den Datensatz an. Ein Mapping wird je Formular-Slug über den Filter wbs_dataverse_connect_bridge_maps deklariert oder in der gleichnamigen Option gespeichert:

add_filter('wbs_dataverse_connect_bridge_maps', function ($maps) {
          $maps['job-application'] = [
              'entity_set' => 'sm_bewerbungs',
              'fields'     => [
                  'first_name' => 'sm_vorname',
                  'email'      => ['column' => 'sm_email', 'type' => 'email'],
                  'birthday'   => ['column' => 'sm_geburtsdatum', 'type' => 'date'],
                  'salutation' => ['column' => 'sm_anrede', 'type' => 'choice',
                                   'options' => ['Mr' => 930860000, 'Ms' => 930860001]],
                  'licenses'   => ['column' => 'sm_fuhrerschein', 'type' => 'multichoice',
                                   'options' => ['C' => 930860000, 'CE' => 930860001]],
                  'privacy'    => ['column' => 'wc_dataprivacypolicyde', 'type' => 'boolean'],
                  'job'        => ['column' => 'sm_job', 'type' => 'lookup', 'nav' => 'sm_Job',
                                   'entity_set' => 'sm_jobs', 'resolve_by' => 'sm_name', 'id_field' => 'sm_jobid'],
              ],
              'defaults'   => ['sm_source' => 930860003],
          ];
          return $maps;
      });

Bridge-Typen: string (Standard), email, int, date, boolean, choice, multichoice, lookup. Auswahlfelder akzeptieren den Optionswert oder eine Beschriftung aus options; Lookups akzeptieren eine GUID oder lösen eine Beschriftung über resolve_by und id_field auf. Ein Mapping kann eine eigene connection tragen, um in eine andere Umgebung zu schreiben. Ist Dataverse nicht erreichbar, wird der Fehler protokolliert und gemeldet, und die eigene E-Mail des Formulars geht trotzdem raus, sodass keine Einsendung verloren geht.

Pro: Contact Form 7 und Gravity Forms

Das Pro-Add-on ordnet ein Contact-Form-7- oder Gravity-Forms-Formular einem auf dem Tab "Forms" konfigurierten Formular zu und schickt die übermittelten Werte durch dieselbe Create-Pipeline. In CF7 fügen Sie unter Additional Settings die Zeile wbsdvc_form: inquiry hinzu; in Gravity Forms setzen Sie den Dataverse form key in den Formulareinstellungen. Übermittelte Feldnamen werden in Kleinbuchstaben umgewandelt und mit den Feldnamen des Formulars abgeglichen. Fehler werden protokolliert und blockieren das Quellformular nie. Details auf der Seite Pro.