„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 unterstützt für:

• Textfelder – Einzeiliger Text (bereinigt als Text).
• 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.

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.

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.

---

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