Der visuelle Spendenformular-Builder ist ein Drag-and-Drop-Formular-Builder, mit dem Sie benutzerdefinierte Spendenformulare für Kampagnen erstellen können. Dieses Dokument enthält technische Details für Entwickler, Designer und Theme-Entwickler, die mit dem visuellen Formular-Builder-System arbeiten.

---

Inhaltsverzeichnis

---

Hooks und Filter

Die folgenden PHP-Hooks und -Filter stehen zur Erweiterung und Anpassung des visuellen Formular-Builders zur Verfügung:

Theme- und Styling-Filter

• charitable_visual_form_theme_classes – Filtert die aufgelösten visuellen Formular-Theme-Klassen (Dichte-Theme)
  • Parameter: $result (Array), $visual_theme (String)
  • Gibt zurück: Array mit dem Schlüssel density_theme
• charitable_visual_form_theme_variables – Filtert die Theme-Variablenzuordnung für visuelle Formulare
  • Parameter: $result (Array), $density_theme (String)
  • Gibt zurück: Array mit dem Schlüssel variables, der CSS-Variablendefinitionen enthält
• charitable_visual_form_default_styles – Filtert Standardstile für visuelle Formulare
  • Parameter: $defaults (Array), $context (String)
  • Gibt zurück: Array mit Standard-Stilwerten
• charitable_visual_form_styles – Filtert das vollständige Styles-Array für ein Formular
  • Parameter: $styles (Array), $campaign_id (int), $form_data (Array)
  • Gibt zurück: Modifiziertes Styles-Array
• charitable_visual_form_field_styles – Filtert Stile für einzelne Felder
  • Parameter: $field_styles (Array), $field_id (String), $field_data (Array), $campaign_id (int)
  • Gibt zurück: Modifiziertes Feld-Styles-Array
• charitable_visual_form_field_classes – Filter CSS-Klassen, die auf Formularfelder angewendet werden
  • Parameter: $classes (array), $field_id (string), $field_data (array), $campaign_id (int)
  • Gibt zurück: Modifizierter Klassen-Array
• charitable_visual_form_field_full_width – Bestimmen, ob ein Feld über die gesamte Breite gehen soll
  • Parameter: $is_full_width (bool), $field_id (string), $field_data (array), $campaign_id (int)
  • Gibt zurück: Boolean
• charitable_visual_form_enable_theme_inheritance – Vererbung von Theme-Stilen aktivieren/deaktivieren
  • Parameter: Keine
  • Gibt zurück: Boolean (Standard: false)
• charitable_visual_form_detected_theme_styles – Erkannte Theme-Stile filtern
  • Parameter: $detected (array), $active_theme (string)
  • Gibt zurück: Modifizierter Array mit erkannten Stilen
• charitable_visual_form_theme_style_map – Erkannte Theme-Stile Formularvariablen zuordnen
  • Parameter: $mapped (array), $detected_styles (array), $theme_name (string)
  • Gibt zurück: Modifizierter Zuordnungs-Array
• charitable_visual_form_theme_fallback – Fallback-Werte für Theme-Variablen bereitstellen
  • Parameter: $fallback (mixed), $form_variable (string), $detected_value (mixed), $context (string)
  • Gibt zurück: Fallback-Wert oder null
• charitable_visual_form_enable_elementor_inheritance – Vererbung von Elementor-Stilen aktivieren/deaktivieren
  • Parameter: Keine
  • Gibt zurück: Boolean (Standard: true)
• charitable_visual_form_detected_elementor_styles – Erkannte Elementor-Stile filtern
  • Parameter: $detected (array), $elementor_active (bool)
  • Gibt zurück: Modifizierter Array mit erkannten Stilen
• charitable_visual_form_elementor_style_map – Elementor-Stile Formularvariablen zuordnen
  • Parameter: $mapped (array), $detected_styles (array)
  • Gibt zurück: Modifizierter Zuordnungs-Array

Mehrstufige Formularfilter

• charitable_multistep_animation_type – Animationstyp für mehrstufige Formulare filtern
  • Parameter: $animation_type (string), $campaign_id (int)
  • Gibt zurück: Animationstyp-String
• charitable_multistep_prev_button_text – Text für die Schaltfläche „Zurück“ filtern
  • Parameter: $text (string), $campaign_id (int)
  • Gibt zurück: Button-Text-String
• charitable_multistep_next_button_text – Filtert den Text des „Weiter“-Buttons
  • Parameter: $text (string), $campaign_id (int)
  • Gibt zurück: Button-Text-String
• charitable_multistep_show_step_number – Steuert, ob Schrittnummern angezeigt werden
  • Parameter: $show (bool), $step_number (int), $campaign_id (int)
  • Gibt zurück: Boolean
• charitable_multistep_step_label – Filtert Schrittbezeichnungen
  • Parameter: $label (string), $step_number (int), $campaign_id (int)
  • Gibt zurück: Schrittbezeichnungs-String

Formular- und Feldaktionen

• charitable_donation_form_before_fields – Aktion, die vor dem Rendern der Formularfelder ausgelöst wird
  • Parameter: $current_form (array)
• charitable_visual_form_before_payment_section – Aktion, die vor dem Rendern des Zahlungsabschnitts ausgelöst wird
  • Parameter: $current_form (array), $campaign_id (int), $visual_form_data (array), $section_index (int per Referenz)
• charitable_visual_form_file_uploaded – Aktion, die ausgelöst wird, wenn eine Datei hochgeladen wird
  • Parameter: $attachment_id (int), $donation_id (int), $file_key (string)

Feldspezifische Filter

• charitable_visual_form_address_country_default – Filtert das Standardland für Adressfelder
  • Parameter: $default_country (string), $campaign_id (int), $field_data (array)
  • Gibt zurück: Ländercode-String
• charitable_donation_form_gateway_fields – Filtert Gateway-spezifische Felder
  • Parameter: $gateway_fields (array), $gateway (object)
  • Gibt zurück: Array mit modifizierten Gateway-Feldern
• charitable_html_field_allowed_html – Filtert erlaubte HTML-Tags für HTML-Felder
  • Parameter: $allowed_html (string|array), $field_data (array), $field_id (string)
  • Gibt zurück: „default“ oder Array mit erlaubtem HTML
• charitable_checkbox_field_use_fieldset – Bestimmt, ob Checkbox-Felder eine fieldset-Umrandung verwenden sollen
  • Parameter: $use_fieldset (bool), $normalized_id (string), $render_data (array), $visual_field_data (array)
  • Gibt zurück: Boolean (Standard: false)
• charitable_visual_form_donate_label – Filtert die Beschriftung des Spenden-Buttons
  • Parameter: $donate_label (string), $campaign_id (int), $visual_form_data (array)
  • Rückgabe: Button-Beschriftung (String)

Formular-Builder-Filter

• charitable_default_visual_form_template – Filtert die Standardvorlage für visuelle Formulare
  • Parameter: $default_template (array), $campaign_id (int), $form_type (string)
  • Rückgabe: Vorlagen-Array
• charitable_form_builder_load_fields – Filtert die Liste der zu ladenden Feldtypen
  • Parameter: $form_fields (array)
  • Rückgabe: Modifiziertes Feldtypen-Array
• charitable_builder_form_buttons – Filtert die Formularfeld-Buttons in der Builder-Seitenleiste
  • Parameter: $fields (array)
  • Rückgabe: Modifiziertes Felder-Array
• charitable_builder_form_field_button_attributes – Filtert Attribute für Formularfeld-Buttons
  • Parameter: $attributes (array), $field (array), $form_data (array)
  • Rückgabe: Modifiziertes Attribute-Array
• charitable_visual_form_conditional_logic_enabled – Bedingte Logik global aktivieren/deaktivieren
  • Parameter: $enabled (bool), $field_data (array)
  • Gibt zurück: Boolean (Standard: true)
• charitable_visual_form_debug – Debug-Modus für visuelle Formulare aktivieren/deaktivieren
  • Parameter: $enable_debug (bool)
  • Gibt zurück: Boolean

---

Feldkategorien und Einstellungen

Felder im visuellen Formular-Builder sind in drei Kategorien unterteilt: Erforderliche Felder, Formularfelder (regulär) und Pro-Felder.

Allgemeine Feldeinstellungen

Die meisten Felder unterstützen die folgenden allgemeinen Einstellungen (Hinweis: Nicht alle Felder haben alle diese Einstellungen):

• Bezeichnung – Die Textbezeichnung, die den Benutzern auf dem Spendenformular angezeigt wird
• Platzhalter – Platzhaltertext, der in leeren Eingabefeldern angezeigt wird
• Erforderlich – Ob das Feld vor dem Absenden des Formulars ausgefüllt werden muss
• Ausrichtung – Feld-Ausrichtung (links, mitte, rechts) – nicht für alle Felder verfügbar
• CSS-Klasse – Benutzerdefinierte CSS-Klassen für das Styling – nicht für alle Felder verfügbar

Erforderliche Felder

Diese Felder sind für Spendenformulare unerlässlich und können normalerweise nur einmal pro Formular hinzugefügt werden.

Spender-Namensfelder

• Typ: spender-namensfelder
• Einstellungen:
  • Layout (nebeneinander oder gestapelt)
  • Beschriftung
  • Ausrichten
  • CSS-Klasse
• Feldlimit: 1 pro Formular
• Kann nicht dupliziert werden

Spender-E-Mail-Feld

• Typ: Spender-E-Mail-Feld
• Einstellungen:
  • Beschriftung
  • Ausrichten
  • CSS-Klasse
• Feldlimit: 1 pro Formular
• Kann nicht dupliziert werden

Adressfelder

• Typ: Adressfelder
• Einstellungen:
  • Beschriftung
  • Ausrichten
  • CSS-Klasse
• Feldlimit: 1 pro Formular
• Kann nicht dupliziert werden
• Hinweis: Enthält Felder für Adresse, Adresszusatz, Stadt, Bundesland, Postleitzahl und Land

Datenschutzrichtlinie

• Typ: Datenschutzrichtlinie
• Einstellungen:
  • Beschriftung
  • Ausrichten
  • CSS-Klasse
• Feldlimit: 1 pro Formular
• Kann nicht dupliziert werden

Spendenbeträge

• Typ: Vorgeschlagene Spendenbeträge
• Einstellungen:
  • Beschriftung
  • Ausrichten
  • CSS-Klasse
• Feldlimit: 1 pro Formular
• Kann nicht dupliziert werden
• Hinweis: Zeigt vorgeschlagene Spendenbeträge aus den Kampagneneinstellungen an

Zahlungsbereich

• Typ: Zahlungsbereich
• Einstellungen:
  • Gateway-Auswahl (Kontrollkästchen für Mehrfachauswahl für verfügbare Zahlungsgateways)
  • Beschriftung
  • Ausrichten
  • CSS-Klasse
• Feldlimit: 1 pro Formular
• Kann nicht dupliziert werden

Formularfelder (Regulär)

Dies sind Standardformularfelder, die zum Erstellen benutzerdefinierter Spendenformulare verfügbar sind.

Einzelnes Textfeld

• Typ: Einzeltext
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Standardwert
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Dropdown-Feld

• Typ: Dropdown
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Mehrfachauswahl zulassen (Kontrollkästchen)
  • Optionsverwaltung (Optionen mit Wert- und Beschriftungspaaren hinzufügen/bearbeiten/entfernen)
  • Standardoption (Radioauswahl)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Kontrollkästchen-Feld

• Typ: Kontrollkästchenfeld
• Einstellungen:
  • Beschriftung
  • Erforderlich
  • Verwaltung von Kontrollkästchen-Optionen (Hinzufügen/Bearbeiten/Entfernen von Kontrollkästchen mit Wert- und Beschriftungspaaren)
  • Standardauswahlen (Kontrollkästchen für vorausgewählte Optionen)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Radiofeld

• Typ: Radiofeld
• Einstellungen:
  • Beschriftung
  • Erforderlich
  • Verwaltung von Radio-Optionen (Hinzufügen/Bearbeiten/Entfernen von Radio-Buttons mit Wert- und Beschriftungspaaren)
  • Standardauswahl (Radioauswahl)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Textbereichsfeld

• Typ: Textbereichsfeld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Zeilen (Anzahl der Textbereichszeilen)
  • Maximale Länge (Zeichenbegrenzung)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

E-Mail-Feld

• Typ: E-Mail-Feld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Telefonfeld

• Typ: Telefonfeld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Nummernfeld

• Typ: Nummernfeld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Minimalwert (optional)
  • Maximalwert (optional)
  • Schritt (Wert erhöhen/verringern)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Datumsfeld

• Typ: Datumsfeld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Datumsformat
  • Mindestdatum (optional)
  • Maximaldatum (optional)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

URL-Feld

• Typ: url-feld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Datei-Feld

• Typ: datei-feld
• Einstellungen:
  • Beschriftung
  • Erforderlich
  • Zulässige Dateitypen (Mehrfachauswahl)
  • Max. Dateigröße (MB)
  • Bildzuschnitt aktivieren (nur für JPEG/PNG)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Editor-Feld (WYSIWYG)

• Typ: editor-feld
• Einstellungen:
  • Beschriftung
  • Erforderlich
  • Editor-Inhalt (Rich-Text-Editor)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Überschriftenfeld

• Typ: ueberschriften-feld
• Einstellungen:
  • Textinhalt
  • Überschriftenebene (H1-H6)
  • Ausrichten
  • CSS-Klasse
  • Hinweis: Verfügt nicht über erweiterte Optionen

Trennlinienfeld

• Typ: trennlinien-feld
• Einstellungen:
  • Stil (durchgezogen, gestrichelt, gepunktet)
  • Breite (Prozent)
  • Ausrichten
  • CSS-Klasse
  • Hinweis: Verfügt nicht über erweiterte Optionen

Bildfeld

• Typ: bild-feld
• Einstellungen:
  • Bildauswahl
  • Alternativtext
  • Link-URL (optional)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

HTML-Feld

• Typ: html-feld
• Einstellungen:
  • HTML-Inhalt (Code-Editor)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen

Shortcode-Feld

• Typ: shortcode-feld
• Einstellungen:
  • Shortcode-Inhalt
  • Ausrichten
  • CSS-Klasse
  • Hinweis: Verfügt nicht über erweiterte Optionen

Verstecktes Feld

• Typ: verstecktes-feld
• Einstellungen:
  • Feldname
  • Standardwert
  • Erweiterte Optionen
  • Hinweis: Verfügt nicht über Einstellungen für Beschriftung, Platzhalter, Erforderlich, Ausrichtung oder CSS-Klasse

Pro-Felder

Diese Felder sind in Charitable Pro verfügbar und erscheinen in der Kategorie „Pro-Felder“.

Spendenkommentarfeld

• Typ: Spendenkommentarfeld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Zeilen (Anzahl der Textbereichszeilen)
  • Maximale Länge (Zeichenbegrenzung)
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen
• Hinweis: Erfordert, dass Spendenkommentare in den Charitable-Einstellungen aktiviert sind

Empfehlungscode-Feld

• Typ: empfehlungscode-feld
• Einstellungen:
  • Beschriftung
  • Platzhalter
  • Erforderlich
  • Ausrichten
  • CSS-Klasse
  • Erweiterte Optionen
• Hinweis: Erfordert, dass Spendenempfehlungen in den Charitable-Einstellungen aktiviert sind

---

Erweiterte Optionen

Erweiterte Optionen sind für die meisten Formularfelder verfügbar (mit einigen Ausnahmen, die oben erwähnt wurden). Diese Optionen steuern, wie Feld-Daten in verschiedenen Kontexten verarbeitet und angezeigt werden.

Im Export anzeigen

Wenn aktiviert, werden die Daten dieses Feldes in Spendenexporten und -berichten enthalten sein. Dies ist nützlich für Felder, die wichtige Spenderinformationen enthalten, die Sie verfolgen und analysieren möchten.

Technische Details: Feld-Daten werden in Spenden-Metadaten gespeichert und einbezogen, wenn Exportfunktionen Spenden-Daten abfragen. Das Feld muss diese Option aktiviert haben, damit seine Daten in CSV-Exporten und anderen Berichtswerkzeugen angezeigt werden.

In E-Mail anzeigen

Wenn aktiviert, wird ein E-Mail-Tag für dieses Feld erstellt, das in E-Mail-Vorlagen verwendet werden kann. Das Tag-Format ist typischerweise {field_field_id} oder ein benutzerdefiniertes Tag basierend auf dem Feldnamen.

Technische Details: E-Mail-Tags werden beim E-Mail-System von Charitable registriert und können in Spendenquittungs-E-Mails, Admin-Benachrichtigungen und anderen E-Mail-Vorlagen verwendet werden. Der Feldwert wird automatisch formatiert und eingefügt, wenn die E-Mail gesendet wird.

In Metadaten anzeigen

Wenn aktiviert, werden die Daten dieses Feldes auf der Admin-Seite für Spenden-Details im Abschnitt Spenden-Metadaten angezeigt. Dies ermöglicht Administratoren, benutzerdefinierte Feld-Daten bei der Überprüfung von Spenden anzuzeigen.

Technische Details: Feld-Daten werden in der Spenden-Metabox auf dem WordPress Admin-Bearbeitungsbildschirm für Spenden angezeigt. Dies bietet eine bequeme Möglichkeit, alle benutzerdefinierten Feld-Daten, die mit einer Spende verbunden sind, anzuzeigen, ohne exportieren oder die Datenbank abfragen zu müssen.

Hinweis: Einige Felder (wie das Spendenkommentarfeld und das Empfehlungscode-Feld) haben „In Metadaten anzeigen“ standardmäßig aktiviert und können nicht deaktiviert werden, da diese Informationen als wesentlich für Spendenaufzeichnungen gelten.

---

Bedingte Logik

Bedingte Logik ermöglicht es Ihnen, Felder basierend auf Werten in anderen Feldern anzuzeigen oder auszublenden. Dies erstellt dynamische, interaktive Formulare, die sich basierend auf Benutzereingaben anpassen.

So funktioniert's

Bedingte Logik verwendet ein regelbasiertes System, bei dem Sie:

1. Bedingte Logik aktivieren – Bedingte Logik für jedes Feld ein-/ausschalten
2. Aktionstyp festlegen – Wählen Sie „Anzeigen“ oder „Ausblenden“, wenn Bedingungen erfüllt sind
3. Regeln erstellen – Bedingungen basierend auf anderen Feldwerten definieren
4. Regeln gruppieren – AND/OR-Logik verwenden, um komplexe Bedingungen zu erstellen

Regelstruktur

• Feld – Wählen Sie das zu prüfende Feld aus
• Operator – Wählen Sie den Vergleichsoperator (gleich, ungleich, enthält usw.)
• Wert – Geben Sie den zu vergleichenden Wert ein

Logikgruppen

Regeln können gruppiert werden mit:

• AND – Alle Regeln in einer Gruppe müssen wahr sein
• OR – Jede Regel in einer Gruppe kann wahr sein (separate Gruppen)

Technische Implementierung

Bedingte Logik wird im Frontend mit JavaScript ausgewertet. Regeln werden im conditionals-Array und im conditional_logic-Flag des Feldes gespeichert. Das System unterstützt die Echtzeitauswertung, während Benutzer mit dem Formular interagieren.

Filter: charitable_visual_form_conditional_logic_enabled – Kann verwendet werden, um bedingte Logik global oder für bestimmte Felder zu deaktivieren.

---

Mehrschrittige Formulare

Mehrschrittige Formulare ermöglichen es Ihnen, Spendenformulare in mehrere Seiten oder Schritte aufzuteilen, was die Benutzererfahrung für längere Formulare verbessert.

Formulararten

• Einseitiges Formular – Alle Felder auf einer Seite (Standard)
• Mehrschrittiges Formular – Felder auf mehrere Schritte/Folien aufgeteilt

Schrittverwaltung

• Mindestanzahl Schritte: 2 Schritte für mehrschrittige Formulare erforderlich
• Maximalanzahl Schritte: 4 Schritte erlaubt
• Schrittbezeichnungen: Jeder Schritt kann eine benutzerdefinierte Bezeichnung haben
• Schrittnavigation: Vorherige/Nächste-Schaltflächen mit anpassbarem Text
• Fortschrittsanzeigen: Visuelle Fortschrittsanzeigen zeigen den Abschluss des Formulars an

Schrittkonfiguration

Schritte (auch „Folien“ genannt) werden im Bereich „Formularoptionen“ verwaltet. Sie können:

• Neue Schritte hinzufügen
• Schritte entfernen (mindestens 2 erforderlich)
• Schritte umbenennen
• Schritte neu anordnen
• Felder bestimmten Schritten zuweisen

Navigation

• Vorherige Schaltfläche – Zurück zum vorherigen Schritt navigieren (auf dem ersten Schritt ausgeblendet)
• Nächste Schaltfläche – Zum nächsten Schritt navigieren (validiert den aktuellen Schritt, bevor fortgefahren wird)
• Senden-Schaltfläche – Nur auf dem letzten Schritt sichtbar
• Schrittüberschriften – Optionale klickbare Schrittüberschriften zur Navigation (kann deaktiviert werden)

Validierung

Jeder Schritt wird validiert, bevor die Weiterleitung zum nächsten Schritt erlaubt wird. Nur Felder, mit denen interagiert wurde, werden validiert, um vorzeitige Validierungsfehler zu vermeiden.

Animation

Schrittübergänge können animiert werden. Der Animationstyp kann über charitable_multistep_animation_type gefiltert werden.

Filter:

• charitable_multistep_prev_button_text – Text für die Schaltfläche „Zurück“ anpassen
• charitable_multistep_next_button_text – Text für die Schaltfläche „Weiter“ anpassen
• charitable_multistep_show_step_number – Anzeige der Schrittnummer steuern
• charitable_multistep_step_label – Schrittbezeichnungen anpassen

---

Feldvalidierung

Die Feldvalidierung stellt sicher, dass Benutzer korrekte und vollständige Informationen vor dem Absenden des Formulars angeben.

Validierungstypen

1. Pflichtfeldvalidierung – Stellt sicher, dass Pflichtfelder nicht leer sind
2. Formatvalidierung – Überprüft das Feldformat (E-Mail, URL, Zahl usw.)
3. Bereichsvalidierung – Überprüft Min/Max-Werte für Zahlen- und Datumsfelder
4. Datei-Validierung – Überprüft Dateityp, -größe und andere Upload-Beschränkungen
5. Benutzerdefinierte Validierung – Feldspezifische Validierungsregeln

Validierungszeitpunkt

• Beim Absenden – Die vollständige Formularvalidierung erfolgt, wenn auf die Schaltfläche „Senden“ geklickt wird
• Beim Schrittwechsel – Mehrschrittformulare validieren den aktuellen Schritt, bevor der nächste Schritt zugelassen wird
• Echtzeit – Einige Felder können validiert werden, während der Benutzer tippt (abhängig vom Browser)

Validierungsaktionen

Jeder Feldtyp verfügt über eine validate() -Methode, die über die charitable_form_process_validate_{field_type} -Aktion aufgerufen wird. Validierungsfehler werden den Benutzern angezeigt und verhindern die Formularübermittlung, bis sie behoben sind.

Fehleranzeige

Validierungsfehler werden angezeigt:

• Unter dem Feld, das die Validierung nicht bestanden hat
• In einer Zusammenfassung am Anfang des Formulars (bei mehreren Fehlern)
• Mit klaren, benutzerfreundlichen Fehlermeldungen

---

Frontend-Rendering

Der visuelle Formular-Builder verwendet ein spezialisiertes Rendering-System, das die Daten des Builders in funktionale HTML-Formulare im Frontend umwandelt.

Rendering-Prozess

1. Abruf von Formulardaten – Formular-Konfiguration wird aus den Kampagnen-Post-Metadaten geladen
2. Feldregistrierung – Felder werden bei der Charitable’s Donation Fields API registriert
3. Vorlagen-Rendering – Felder werden mit Theme-fähigen Vorlagen gerendert
4. Stilanwendung – CSS-Klassen und Inline-Stile werden basierend auf den Formulareinstellungen angewendet
5. JavaScript-Initialisierung – Frontend-JavaScript behandelt Interaktionen und Validierung

Rendering-Klassen

Formulare erhalten CSS-Klassen basierend auf:

• Formular-Typ (einseitig oder mehrstufig)
• Themenauswahl
• Dichte-Einstellungen
• Benutzerdefinierte CSS-Klassen

Feld-Wrapper

Jedes Feld ist in Container verpackt, die Folgendes bieten:

• Konsistente Abstände und Layout
• Ausrichtungsunterstützung
• Responsives Verhalten
• Themenintegration

Mehrstufiges Rendering

Mehrstufige Formulare werden gerendert mit:

• Schritt-Container, die basierend auf dem aktuellen Schritt ein-/ausgeblendet werden
• Navigationssteuerung
• Fortschrittsanzeigen
• Schrittspezifische Validierung

---

Theme-Integration

Der visuelle Formular-Builder beinhaltet eine ausgefeilte Themenintegration, die Formulare automatisch an die Stile Ihres aktiven WordPress-Themes oder Page-Builders anpasst.

Themenerkennung

Das System erkennt automatisch:

• Aktives WordPress-Theme
• Elementor Page Builder-Stile (falls aktiv)
• Farbpaletten und Typografie des Themes

Stil-Vererbung

Formulare können Stile erben von:

• WordPress Themes – Erkennt und wendet automatisch Theme-Farben, Schriftarten und Abstände an
• Elementor – Erbt Elementor globale Farb- und Typografie-Einstellungen
• Benutzerdefinierte CSS-Variablen – Verwendet benutzerdefinierte CSS-Eigenschaften für einfache Thematisierung

CSS-Variablen

Formulare verwenden benutzerdefinierte CSS-Eigenschaften (Variablen) für die Gestaltung, was eine einfache Anpassung ermöglicht:

• --charitable-field-gap – Abstand zwischen Feldern
• --charitable-input-padding-y – Vertikales Padding für Eingabefelder
• --charitable-input-padding-x – Horizontales Padding für Eingabefelder
• --charitable-input-border-color – Rahmenfarbe für Eingabefelder
• --charitable-input-border-radius – Rahmenradius für Eingabefelder
• --charitable-focus-ring-color – Fokusring-Farbe
• Und mehr…

Theme-Klassen

Formulare erhalten themenspezifische CSS-Klassen, die es Theme-Entwicklern ermöglichen, Formulare mit benutzerdefinierten Stilen anzusprechen:

• Dichteklassen (Basis, Abstände)
• Themenspezifische Klassen
• Formular-Typ-Klassen (einzeln, mehrstufig)

Für Theme-Entwickler

Um visuelle Formulare in Ihrem Theme anzupassen:

1. CSS-Variablen verwenden – Überschreiben Sie benutzerdefinierte CSS-Eigenschaften in Ihrer Theme-Stylesheetdatei
2. Themenklassen ansprechen – Verwenden Sie die Themenklassen, die auf Formulare angewendet werden, für spezifische Stile
3. Filter verwenden – Haken Sie in Theme-Erkennungsfilter ein, um die Stil-Vererbung anzupassen
4. Benutzerdefinierte CSS-Klassen – Fügen Sie benutzerdefinierte CSS-Klassen zu Feldern über die Einstellung „CSS-Klasse“ hinzu

Filter für Theme-Integration

• charitable_visual_form_theme_classes – Themenklassen ändern
• charitable_visual_form_theme_variables – CSS-Variablen anpassen
• charitable_visual_form_enable_theme_inheritance – Theme-Vererbung aktivieren/deaktivieren
• charitable_visual_form_detected_theme_styles – Erkannte Theme-Stile ändern
• charitable_visual_form_theme_style_map – Stilzuordnung anpassen
• charitable_visual_form_theme_fallback – Fallback-Werte bereitstellen

Für Designer

Der visuelle Formular-Builder bietet:

• Konsistentes Styling – Formulare passen sich automatisch dem Design Ihrer Website an
• Responsives Layout – Formulare passen sich an verschiedene Bildschirmgrößen an
• Barrierefreiheit – Formulare folgen den Best Practices für Barrierefreiheit
• Anpassungsoptionen – Einfach zu bedienende Einstellungen für Farben, Abstände und Layout

Dichte-Designs

Zwei Dichtungsoptionen sind verfügbar:

• Basis – Standardabstand (Standard)
• Abstand – Erhöhter Abstand für bessere Lesbarkeit

Die Dichte beeinflusst Feldabstände, Eingabepolsterung und den gesamten Formularabstand.

---

Feldduplizierung

Felder können dupliziert werden, um schnell ähnliche Felder mit denselben Einstellungen zu erstellen.

Duplizierungsprozess

1. Klicken Sie auf das Duplizieren-Symbol bei einem beliebigen Feld
2. Wählen Sie den Duplizierungsmodus:
   • Einstellungen kopieren – Dupliziert das Feld mit allen Einstellungen (außer bedingter Logik und erweiterten Optionen)
   • Standardwerte verwenden – Erstellt ein neues Feld mit Standardeinstellungen, behält aber das ursprüngliche Label bei (mit angehängtem „(Kopie)“)

Was wird dupliziert

Beim Kopieren von Einstellungen:

• Feld-Label (mit angehängtem „(Kopie)“, falls nicht bereits vorhanden)
• Feldtyp
• Alle feldspezifischen Einstellungen (Optionen, Platzhalter usw.)
• Erforderlicher Status
• Ausrichtung
• CSS-Klassen
• Standardwerte

Was NICHT dupliziert wird

• Bedingte Logik (immer zurückgesetzt)
• Erweiterte Optionen (immer zurückgesetzt)
• Feld-ID (neue eindeutige ID zugewiesen)

Feld-ID-Verwaltung

Jedes duplizierte Feld erhält eine neue, eindeutige Feld-ID. Das System verwendet Transienten, um die nächste verfügbare Feld-ID zu verfolgen und Konflikte zu vermeiden.

---

Feldgrenzen und -beschränkungen

Bestimmte Felder haben Einschränkungen, wie oft sie zu einem Formular hinzugefügt werden können.

Felder mit Limits

Die folgenden Felder können nur einmal pro Formular hinzugefügt werden:

• Spender-Namensfelder (max_allowed: 1)
• Spender-E-Mail-Feld (max_allowed: 1)
• Adressfelder (max_allowed: 1)
• Datenschutzrichtlinie (max_allowed: 1)
• Spendensummen (max_allowed: 1)
• Zahlungsbereich (max_allowed: 1)

Felder, die nicht dupliziert werden können

Einige Felder können nicht dupliziert werden, auch wenn sie keine strenge Grenze haben:

• Alle oben aufgeführten Pflichtfelder
• Zahlungsbereich

Mehrschritt-Formular-Limits

• Mindestanzahl Schritte: 2 Schritte für mehrschrittige Formulare erforderlich
• Maximalanzahl Schritte: 4 Schritte erlaubt

Feldverfügbarkeit

Einige Felder erfordern bestimmte Einstellungen, um aktiviert zu werden:

• Spender-Kommentarfeld – Erfordert, dass Spenderkommentare in Charitable → Einstellungen → Spender aktiviert sind
• Überweisungscode-Feld – Erfordert, dass Spenderüberweisungen in Charitable → Einstellungen → Spender aktiviert sind

Diese Felder werden im Builder deaktiviert, wenn die erforderlichen Einstellungen nicht aktiviert sind, mit einem Modal, das erklärt, wie sie aktiviert werden können.

---

Limit für die Spendeneingabe durch Administratoren

Wichtig: Wenn Sie manuell eine Spende im WordPress-Adminbereich hinzufügen (über Spenden → Neu hinzufügen), werden die benutzerdefinierten Felder des visuellen Formular-Builders nicht unterstützt oder angezeigt.

Nur über das Frontend-Formular eingereichte Spenden erfassen und speichern benutzerdefinierte Felddaten. Im Adminbereich erstellte Spenden haben keinen Zugriff auf:

• Benutzerdefinierte Felder, die über den visuellen Builder hinzugefügt wurden
• Feldspezifische Validierung
• Speicherung benutzerdefinierter Felddaten
• Erweiterte Optionen Einstellungen

Diese Einschränkung besteht, da die Benutzeroberfläche für die Spendeneingabe im Adminbereich das Standard-Spendenformular von Charitable verwendet und nicht das System des visuellen Formular-Builders. Im visuellen Builder erstellte benutzerdefinierte Felder werden nur verarbeitet und gespeichert, wenn Spenden über das Frontend-Formular eingereicht werden.

---

Zusätzliche Ressourcen

Weitere Informationen zur Erweiterung des visuellen Formular-Builders finden Sie hier:

• Charitable Entwicklerdokumentation
• WordPress Hooks und Filter Dokumentation
• Charitable GitHub Repository

---

Dokumentversion: 1.0 Zuletzt aktualisiert: 28. November 2025