„Vorausfüllung für Spendenformulare“ ist eine neue Funktion ab Charitable Pro 1.8.13, mit der Sie Spendenformularfelder über URL-Parameter vorab ausfüllen können. Wenn ein Spender eine Spendenseite mit der richtigen Abfragestruktur öffnet, können Felder wie Name, E-Mail, Adresse und benutzerdefinierte Formularfelder (Text, Radio, Checkbox, Auswahl, Adresse) automatisch ausgefüllt werden. Dies ist nützlich für E-Mail-Kampagnen, Landingpages oder Links aus externen Systemen, bei denen Sie Spender- oder Kontextdaten in das Formular übergeben möchten.

Inhaltsverzeichnis

Voraussetzungen

• Charitable Pro: Version 1.8.13 oder höher
• WordPress: Version 6.2 oder höher
• PHP: Version 7.4 oder höher

URL-Vorausfüllung muss pro Kampagne aktiviert (siehe unten) sein. Sie funktioniert sowohl mit dem Standard-Spendenformular als auch mit dem Visual Form Builder (benutzerdefinierte Felder, Adressfelder, Radio, Checkbox, Auswahl).

URL-Vorausfüllung aktivieren

1. Bearbeiten Sie die Kampagne, deren Spendenformular Sie vorausfüllen möchten.
2. Öffnen Sie den Campaign Builder (oder den Formular-/Einstellungsbereich, in dem das Spendenformular konfiguriert ist).
3. Suchen Sie den Schalter URL-Vorausfüllung aktivieren (in den Anzeigeoptionen des Formulars, in der Nähe von Visuelles Formular aktivieren).
4. Schalten Sie URL-Vorausfüllung aktivieren ein und speichern Sie die Kampagne.

Wenn die URL-Vorausfüllung für die Kampagne deaktiviert ist, werden Abfrageparameter ignoriert und keine Felder vorausgefüllt. Wenn sie aktiviert ist, werden nur Parameter verwendet, die den erlaubten Feldschlüsseln entsprechen und die Bereinigung bestehen.

Parameterformat

• Präfix: Standardmäßig müssen alle Vorausfüllparameter das cf_ -Präfix verwenden.
  Beispiel: ?cf_first_name=Jane&cf_last_name=Doe
• Feldschlüssel: Nach dem Präfix muss der Parametername mit dem Feldschlüssel des Formulars übereinstimmen (z. B. first_name, last_name, email oder benutzerdefinierte Feldschlüssel wie field_7 für Felder des visuellen Formulars).
• Wert: Der Wert wird entsprechend dem Feldtyp bereinigt (Text, E-Mail, URL, Textbereich usw.). Werte, die die Bereinigung nicht bestehen oder die maximale Länge überschreiten, werden verworfen.

Beispiel-URL:

https://yoursite.com/campaigns/my-campaign/?cf_first_name=Jane&cf_last_name=Doe&[email protected]

Optional: Sie können die Anforderung des cf_ -Präfixes mit dem Filter charitable_prefill_use_prefix (siehe Entwicklerressourcen) entfernen. In diesem Fall würden Parameter wie ?first_name=Jane gelesen. Die Verwendung des Präfixes wird empfohlen, um Konflikte mit anderen Plugins oder WordPress-Abfragevariablen zu vermeiden.

Unterstützte Feldtypen

Vorausfüllung wird für die unten aufgeführten Feldtypen unterstützt und nur für diese. Ein Feldtyp, der nicht aufgeführt ist, ignoriert den Parameter.

• Textfelder – Einzeiliger Text (bereinigt als Text).
• Versteckt – Überträgt einen von Ihnen bereitgestellten Wert anstelle eines vom Spender eingegebenen Werts. Angesprochen über seinen Feldnamen anstelle einer Feld-ID, sodass ein verstecktes Feld namens source durch ?cf_source= gefüllt wird. Benötigt Charitable Pro 1.8.18 oder höher.
• Radio – Ein Optionswert; der URL-Wert muss mit einem Optionswert übereinstimmen, um ihn auszuwählen.
• Checkbox – Ein oder mehrere Optionswerte. Verwenden Sie eine kommagetrennte Liste in einem einzelnen Parameter, um mehrere Optionen vorab auszuwählen (z. B. cf_my_checkbox=opt1,opt2).
• Select – Einzelner Optionswert (oder der ausgewählte Wert für Dropdowns mit einfacher Auswahl). Für Mehrfachauswahl gilt das gleiche kommagetrennte Verhalten wie bei Checkboxen, wo zutreffend.
• Adressfelder – Unterfelder werden mit den Schlüsseln unterstützt: address, address_2, city, state, postcode, country.
  Beispiel: ?cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=US

Zusätzliches Verhalten:

• E-Mail – Parameternamen, die email enthalten (z. B. user_email, email), werden mit sanitize_email() bereinigt.
• URL / Website – Schlüssel wie url, website oder solche, die _url enthalten, werden mit esc_url_raw() bereinigt.
• Textarea-ähnliche Felder – Schlüssel wie message, comment, notes, description, special_message verwenden sanitize_textarea_field().

Felder, die niemals vorab ausgefüllt werden (Sicherheit), umfassen: campaign_id, donation_amount, amount, gateway, password, Zahlungs- und Nonce-Felder sowie andere sensible oder interne Schlüssel. Die vollständige Liste kann von Entwicklern erweitert oder geändert werden (siehe Entwicklerressourcen).

Parameternamen und Beispiele

Gängige Spenderfelder

Parameter	Beschreibung	Beispielwert
cf_first_name	Vorname des Spenders	Jane
cf_last_name	Nachname des Spenders	Doe
cf_user_email	E-Mail des Spenders	[email protected]
cf_email	Alternativer E-Mail-Schlüssel (falls das Formular ihn verwendet)	[email protected]

Adressfelder

Parameter	Beschreibung	Beispielwert
cf_address	Adresszeile 1	123 Main St
cf_address_2	Adresszeile 2	Apt 4
cf_city	Stadt	Boston
cf_state	Bundesland/Region	MA
cf_postcode	Postleitzahl/ZIP	02101
cf_country	Ländercode	US

Benutzerdefinierte Felder des visuellen Formulars

• Benutzerdefinierte Felder im Visual Form Builder verwenden interne Schlüssel wie field_7 (wobei 7 die Feld-ID ist). Verwenden Sie denselben Schlüssel mit dem cf_ -Präfix.
  Beispiel: ?cf_field_7=Mein+Wert
• In einigen Kontexten wird auch die numerische ID akzeptiert (z. B. kann cf_7 field_7 zugeordnet werden). Bevorzugen Sie cf_field_N zur besseren Lesbarkeit, wenn dies von Ihrem Formular dokumentiert wird.
• Versteckte Felder sind die Ausnahme. Ein verstecktes Feld wird über den Feldnamen angesprochen, den Sie im Builder eingegeben haben, nicht über eine Feld-ID. Ein Feld namens source wird durch ?cf_source=spring-appeal gefüllt. Derselbe Name wird für die Formulareingabe, den Parameter und den Schlüssel verwendet, unter dem der Wert nach der Spende gespeichert wird, sodass nur ein Name zu merken ist. Ganze URLs werden akzeptiert, sodass Sie eine vollständige Verweisadresse anstelle eines Slugs übergeben können.

Radio und Auswahl

• Verwenden Sie den exakten Optionswert, der im Formular angezeigt wird.
  Beispiel: für eine „Land“-Auswahl mit dem Wert US, verwenden Sie ?cf_country=US.

Checkbox (mehrere)

• Verwenden Sie einen Parameter mit kommagetrennten Optionswerten.
  Beispiel: für ein Kontrollkästchenfeld mit den Optionen newsletter und updates, verwenden Sie ?cf_interests=newsletter,updates(ersetzen Sie interests durch Ihren Feldschlüssel).

Vollständiges Beispiel-URL

https://yoursite.com/donate/?cf_first_name=Jane&cf_last_name=Doe&cf_user_email=jane%40example.com&cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=US

Verwenden Sie die richtige URL-Kodierung (z. B. %20 für Leerzeichen, %40 für @ in E-Mails).

Sicherheit und Limits

• Blockierte Schlüssel: Sensible und interne Schlüssel (z. B. donation_amount, gateway, password, Nonces) werden niemals aus der URL gelesen. Spendenbetrag und Zahlungsmethode können nicht per Query-String vorausgefüllt werden.
• Max. Parameter: Die Anzahl der aus der URL gelesenen Prefill-Parameter ist begrenzt (Standard 20). Dies kann mit dem Filter charitable_prefill_max_params geändert werden.
• Max. Länge: Jeder Wert wird auf eine maximale Länge (Standard 500 Zeichen) gekürzt. Dies kann mit dem Filter charitable_prefill_max_value_length geändert werden.
• Bereinigung: Alle Werte werden nach Feldtyp bereinigt (Text, E-Mail, URL, Textbereich). Ungültige oder leere Ergebnisse nach der Bereinigung werden nicht angewendet.
• Pro Kampagne: Prefill wird nur ausgeführt, wenn URL-Prefill aktivieren für diese Kampagne aktiviert ist. Für Kampagnen, bei denen es deaktiviert ist, wird kein Prefill angewendet.

Wo Sie den Wert danach finden

Ein vorausgefüllter Wert wird mit der Spende gespeichert. Es gibt drei Stellen, an denen Sie ihn zurücklesen können.

1. Die Spendendetails-Anzeige. Öffnen Sie die Spende unter Charitable > Spenden und sehen Sie sich die Zusammenfassung auf der rechten Seite an. Das Feld erscheint unter seiner Beschriftung mit dem erfassten Wert.
2. Der Spenden-CSV-Export. Öffnen Sie unter Charitable > Spenden das Export-Panel und das Feld erscheint unter Benutzerdefinierte Felder aus visuellen Formularen. Sobald die Exportoption aktiviert ist, wird der Wert als eigene Spalte mit der Beschriftung des Feldes angezeigt.
3. Direkt, für Entwickler. Der Wert wird als Post-Meta auf der Spende unter dem eigenen Namen des Feldes ohne Präfix gespeichert, sodass ein Feld namens source zu Post-Meta source wird.

Wählen, wo er erscheint

Der Abschnitt Erweiterte Optionen jedes Feldes im Kampagnen-Builder steuert dies.

Option	Was es tut	Standard für ein verstecktes Feld
Im Export aktivieren	Fügt eine Spalte zum Spenden-CSV-Export hinzu	Ein
In Spenden-Meta aktivieren	Zeigt den Wert auf der Spendendetails-Anzeige an	Ein
E-Mail-Tags aktivieren	Erstellt ein E-Mail-Tag zur Verwendung in E-Mail-Vorlagen	Aus
In Automatisierungs-Webhooks senden	Schließt das Feld in Automatisierungs-Connect-Payloads ein	Aus

Beide Standardeinstellungen sind für ein verstecktes Feld aktiviert, da ein Feld, dessen Zweck darin besteht, Informationen weiterzugeben, nicht sehr nützlich ist, wenn die Informationen nicht zurückgelesen werden können.

Ein verstecktes Feld, das vor Charitable Pro 1.8.18 erstellt wurde, ist die Ausnahme. Frühere Versionen hatten keine Steuerung dafür und speicherten eine „Aus“-Einstellung für jedes versteckte Feld, sodass Charitable dies als Ihre Präferenz behandelt, anstatt es zu überschreiben. Um eines dieser Felder zu exportieren, öffnen Sie es im Kampagnen-Builder, erweitern Sie Erweiterte Optionen und aktivieren Sie Im Export aktivieren. Versteckte Felder, die ab Version 1.8.18 hinzugefügt wurden, werden standardmäßig exportiert.

Ein Feld, das nichts erfasst hat

Ein Feld, das keinen Wert erfasst hat, schreibt keine Zeile, sondern eine leere. Wenn Sie einen Wert erwarten und das Feld gar nicht in der Spende finden, ist der Wert nicht angekommen. Überprüfen Sie zuerst den Umschalter für die URL-Vorausfüllung der Kampagne und dann, ob der Parametername exakt mit dem Feldnamen übereinstimmt.

Die verweisende Seite automatisch aufzeichnen

Wenn Sie möchten, dass die verweisende Seite aufgezeichnet wird, ohne jedem Link einen Parameter hinzuzufügen, fügen Sie das {referrer} Merge-Tag in den Feldwert eines versteckten Feldes ein, anstatt einen URL-Parameter zu verwenden. Charitable füllt dies im Browser aus, von der Seite, von der der Spender kam.

Das Ausfüllen im Browser anstatt auf dem Server macht es auf einer gecachten Seite sicher. Ein auf dem Server ermittelter Wert wird zusammen mit dem Rest der Seite in Ihrem Seiten-Cache gespeichert, sodass jeder Spender nach dem ersten Spender von dort aufgezeichnet würde, woher der erste kam. Da der Browser ihn ausfüllt, funktioniert er auch innerhalb eines Spenden-Modals. Für Besucher mit deaktiviertem JavaScript wird nichts aufgezeichnet, was beabsichtigt ist: Ein Leerwert ist nützlicher als eine fälschlicherweise sichere Antwort darauf, woher eine Spende stammt.

Fehlerbehebung

Felder werden nicht vorausgefüllt

• Bestätigen Sie, dass URL-Prefill aktivieren für die Kampagne aktiviert ist (Kampagnen-Builder → Formularoptionen).
• Überprüfen Sie, ob die URL das cf_ -Präfix verwendet (z. B. cf_first_name, nicht first_name), es sei denn, Sie haben das Präfix per Filter deaktiviert.
• Stellen Sie sicher, dass der Parametername mit dem Feldschlüssel übereinstimmt (z. B. user_email oder email für das E-Mail-Feld, field_7 für ein benutzerdefiniertes Feld mit der ID 7).
• Für Auswahl-/Radio-/Kontrollkästchen muss der Wert exakt mit einem Optionswert im Formular übereinstimmen.

Wert ist abgeschnitten oder leer

• Werte werden auf die maximale Länge (standardmäßig 500 Zeichen) gekürzt. Verwenden Sie den Filter charitable_prefill_max_value_length, wenn Sie längere Werte benötigen.
• Wenn der Wert nach der Bereinigung leer ist (z. B. ungültige E-Mail), wird er nicht angewendet. Prüfen Sie die Kodierung (z. B. %40 für @ in E-Mails).

Adress-Unterfelder werden nicht ausgefüllt

• Verwenden Sie die exakten Schlüssel: address, address_2, city, state, postcode, country. Sie werden wie andere Parameter mit einem Präfix versehen: cf_address, cf_city usw.
• Stellen Sie sicher, dass das Formular der Kampagne tatsächlich Adressfelder enthält und dass die URL-Vorausfüllung für die Kampagne aktiviert ist.

Benutzerdefinierte Felder des visuellen Formulars

• Verwenden Sie das Schlüsselformat field_N (z. B. cf_field_7), wobei N die ID des benutzerdefinierten Felds ist. Überprüfen Sie den Formular-Builder oder inspizieren Sie die name-Attribute des Formulars, um die IDs zu bestätigen.

Entwicklerressourcen

Filter

• charitableprefilluse_prefix – apply_filters( 'charitable_prefill_use_prefix', true )
  Geben Sie false zurück, um Parameter ohne das cf_-Präfix zuzulassen (z. B. ?first_name=Jane). Standard true.
• charitableprefillenabled – apply_filters( 'charitable_prefill_enabled', $enabled, $campaign_id )
  Überschreiben Sie, ob die URL-Vorausfüllung für eine Kampagne aktiviert ist. Geben Sie true oder false zurück; geben Sie null zurück, um die gespeicherte Einstellung der Kampagne zu verwenden.
• charitableprefillmax_params – apply_filters( 'charitable_prefill_max_params', 20 )
  Maximale Anzahl von URL-Parametern, die für die Vorausfüllung gelesen werden sollen. Standard 20.
• charitableprefillmaxvaluelength – apply_filters( 'charitable_prefill_max_value_length', 500, $field_key )
  Maximale Zeichenlänge pro Wert. Standard 500.
• charitableprefillblocked_keys – apply_filters( 'charitable_prefill_blocked_keys', $blocked_keys )
  Schlüssel hinzufügen oder entfernen, die niemals aus der URL vorausgefüllt werden dürfen (z. B. sicherheitssensible Feldnamen).
• charitableprefillsanitize_value – apply_filters( 'charitable_prefill_sanitize_value', $sanitized, $field_key, $value )
  Ändern Sie den bereinigten Wert, bevor er auf das Feld angewendet wird.

Klasse und Methoden

• CharitableFormPrefill::get_instance() – Gibt die Singleton-Instanz zurück.
• getprefillvalues( $campaign_id ) – Gibt ein Array aller geparsten Vorausfüllwerte (field_key => value) für die aktuelle Anfrage und Kampagne zurück.
• getvalue( $key, $campaignid ) – Gibt den Vorausfüllwert für einen einzelnen Feldschlüssel zurück oder null, wenn er nicht gesetzt ist. Behandelt die Zuordnung von field_N / numerischen Schlüsseln für benutzerdefinierte Felder des visuellen Formulars.
• isenabledforcampaign( $campaignid ) – Gibt zurück, ob die URL-Vorausfüllung für die angegebene Kampagne aktiviert ist.
• hasprefillparams() – Gibt zurück, ob die aktuelle Anfrage URL-Parameter für das Vorabfüllen enthält (nützlich für einen frühen Abbruch).
• reset() – Löscht die zwischengespeicherten analysierten Werte (z. B. für Tests).

Versionshistorie

Version	Änderungen
1.8.13	URL-Abfragezeichenfolgen-Vorabfüllung für Spendenformularfelder (Text, Radio, Kontrollkästchen, Auswahl, Adresse). cf_ -Präfix, kampagnenbezügliche Umschaltung, Bereinigung nach Feldtyp, blockierte Schlüssel und Filter.
1.8.18	Versteckte Felder können vorausgefüllt werden, adressiert nach ihrem Feldnamen. Erfasste Werte werden jetzt auf dem Spenden-Detailbildschirm angezeigt und können als Spenden-CSV-Exportspalte aufgenommen werden, gesteuert pro Feld in den erweiterten Optionen. Fügt das {referrer} Merge-Tag für versteckte Felder hinzu.

---

Zum Erstellen des Spendenformulars und benutzerdefinierter Felder siehe den Visual Form Builder und die Dokumentation zum Spendenformular.