Erfordert: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Visueller Vorlagenmodus ermöglicht es Ihnen, eine einzelne Kampagne mit dem Charitable Visual Campaign Builder zu gestalten – Blöcke verschieben, Typografie festlegen, eine Spenderwand platzieren, einen Sponsorenstreifen hinzufügen.

Anschließend können Sie festlegen, dass jeder Botschafter-Spendenlauf dieses Design erbt, personalisiert für jeden Botschafter.

• Ihr Name, wo Platzhalter sitzen.
• Ihre Geschichte, wo der Story-Block der Vorlage sitzt.
• Ihr Bild, wo das Heldenbild der Vorlage sitzt.
• Ihr Fortschritt im Vergleich zu Ihrem Ziel, wo die Fortschrittsleiste der Vorlage sitzt.

Es ist der Unterschied zwischen jedem Spendenlauf, der gleich aussieht (langweilig), und jedem Spendenlauf, der konsistent aussieht (markenkonform). Die Vorlage ist die Markenschicht; der Inhalt des Botschafters füllt die Details aus.

Wann Sie es verwenden würden

• Gesponserte Veranstaltungen – der Gold-Tier-Sponsor des Marathons möchte sein Logo auf jeder Botschafterseite haben. Die Vorlage trägt den Logo-Block; jeder Spendenlauf erbt ihn.
• Strikte Markenprogramme – Ihr Visual Identity Team möchte die genaue Kontrolle darüber haben, wie jede Seite gerendert wird. Entwerfen Sie es einmal; sperren Sie es.
• A/B-Tests – Klonen Sie die Vorlage, bearbeiten Sie den Text, tauschen Sie aus, welche Vorlage aktiv ist; jeder Spendenlauf tauscht in Echtzeit.
• Kinoreife Anliegen – Gedenkkampagnen, Gala-Spendenläufe – das gleiche Heldenbild, die gleiche Farbpalette, der gleiche emotionale Rhythmus über jeden Botschafter hinweg.

Die visuellen Vorlagen finden

Gehen Sie in Ihrem WordPress-Admin zu Charitable » Botschafter » Vorlagen

Der Unter-Tab Vorlagen hat drei Einstellgruppen:

1. Frontend-Vorlagenstil – der Legacy / Enhanced / Visual-Auswähler. Hier schalten Sie den visuellen Modus ein.
2. Botschafter-Vorlagenkampagne – der Kampagnenauswähler, der auswählt, welche vorhandene Kampagne als Vorlage dient. Wird nur angezeigt, wenn Visual ausgewählt ist.
3. Frontend-Vorlage – der Layout-Varianten-Auswähler (derselbe wie der Unter-Tab Botschafterseite). Wenn eine Vorlagenkampagne konfiguriert ist, ist dies nur informativ – die Vorlage gewinnt.

Auswahl eines Frontend-Vorlagenstils

Drei Modi, jeder zunehmend leistungsfähiger:

Modus	Rendert Botschafterseiten mit…
Altbestand	Die ursprünglichen 1.x-Vorlagen. CSS und Markup unverändert. Wählen Sie dies, wenn Sie Vorlagen oder CSS angepasst haben und nichts ändern möchten.
Erweitert	Die 3.0-Vorlagen (Fortschrittsbalken, Symbolstatistiken, Teilen-Popover, Suche) auf den vorhandenen Seiten. Verwendet den Layout-Auswähler für Botschafterseiten für die Form.
Visuell	Jede Botschafterseite wird aus einem von Ihnen unten ausgewählten Visual Campaign Builder-Layout gerendert. Maximale Kontrolle.

Sie können jederzeit zwischen den Modi wechseln. Der Wechsel zurück zu Legacy verwirft keine gespeicherten Einstellungen – der Vorlagenkampagnen-Zeiger des visuellen Modus bleibt erhalten, sodass Sie später zurückwechseln können.

Auswahl einer Vorlagenkampagne

Sobald Visual ausgewählt ist, erscheint der Botschafter-Vorlagenkampagne-Auswähler.

Der Auswähler wird per Autovervollständigung gesteuert – beginnen Sie mit der Eingabe des Titels Ihrer Vorlage, wählen Sie aus den Ergebnissen. Er bietet nur Kampagnen an, die:

• Wurden im Visual Campaign Builder geöffnet (haben campaign_settings_v2 Post-Meta).
• Sind nicht die Spendenaktion, die Sie rendern werden (keine Endlosschleife).
• Übergibt jeden von Ihnen hinzugefügten charitable_ambassadors_onboarding_visual_template_candidates-Filter.

Wählen Sie eine aus, speichern Sie sie, und der visuelle Modus ist aktiv. Jede Botschafter-Spendenaktion auf Ihrer Website wird jetzt mit dem Design dieser Kampagne gerendert.

Wie die Ersetzung funktioniert

Wenn ein Besucher eine Botschafter-Spendenaktionsseite lädt, fängt Ambassadors den get_post_metadata-Filter für den Meta-Schlüssel campaign_settings_v2 der Kampagne ab. Folgendes passiert:

1. Pro fragt die Builder-Daten von campaign_settings_v2 der Spendenaktion ab.
2. Ambassadors prüft: Sind wir im visuellen Modus? Ist eine Vorlage konfiguriert? Ist dies eine Spendenaktionsseite (nicht die Vorlage selbst)? Hat diese Spendenaktion eigene Builder-Daten (wenn ja, gelten die eigenen Daten der Spendenaktion)?
3. Wenn alle Prüfungen erfolgreich sind, klont Ambassadors die campaign_settings_v2 der Vorlage tief, schreibt id auf die ID der Spendenaktion und title auf den Titel der Spendenaktion um.
4. Jede Zeichenkette in den geklonten Daten wird durch den Token-Substitutionsmechanismus geleitet – jedes {ambassador_name}, {parent_title}, {percent_raised} usw. wird durch die tatsächlichen Werte der Spendenaktion ersetzt.
5. Pro liest die ersetzten Daten und rendert. Jeder dynamische Block (Spendenformular, Fortschrittsbalken, Spenderwand) bindet zur Renderzeit an die ID der Spendenaktion.

Das Ergebnis: eine Spendenaktionsseite, die genau wie die Vorlage aussieht, aber mit den Inhalten des richtigen Botschafters.

Verfügbare Tokens

Sie können alle diese Tokens in den Textfeldern, Alt-Texten, Bildunterschriften usw. der Vorlage verwenden:

Token	Ersetzt durch
{title}	Der Beitragstitel der Spendenaktion.
{ambassador_name}	Der Anzeigename des Autors.
{parent_title}	Der Titel der übergeordneten Kampagne.
{parent_url}	Die Permalink der übergeordneten Kampagne.
{goal}	Das Spendenziel der Spendenaktion (formatiert).
{raised}	Der gesammelte Betrag der Spendenaktion (formatiert).
{donor_count}	Die Anzahl der einzelnen Spender.
{percent_raised}	Fortschritt als Prozentsatz (z. B. 42%).
{fundraiser_image}	URL des Beitragsbildes.

Fügen Sie sie überall im Textinhalt der Vorlage ein. Zum Beispiel wird eine Hero-Überschrift von „Helfen Sie {ambassador_name}, ihr {goal} Ziel zu erreichen“ zu „Helfen Sie Sarah Chen, ihr 5.000-Dollar-Ziel zu erreichen“ auf Sarahs Spendenaktion, „Helfen Sie Marcus Liu, sein 2.500-Dollar-Ziel zu erreichen“ auf Marcus’ Spendenaktion.

Individuelle Überschreibungen pro Spendenaktion

Eine Spendenaktion kann die Vorlage ablehnen, indem sie ihre eigenen campaign_settings_v2 Metadaten hat. Wenn Sie (oder der Botschafter) eine bestimmte Spendenaktion im Visual Campaign Builder öffnen und speichern, gewinnen die Daten dieser Spendenaktion von nun an – die Vorlage gilt nicht mehr für sie.

Um das Design der Vorlage auf einer Spendenaktion wiederherzustellen, die ihren eigenen Weg gegangen ist: Löschen Sie die campaign_settings_v2 Post-Meta auf dieser Spendenaktion:

delete_post_meta( $fundraiser_id, 'campaign_settings_v2' );

Die nächste Seitenladung wird die Vorlage erneut anwenden.

Dynamische Blöcke funktionieren weiterhin

Auch wenn die Struktur der Vorlage auf jede Spendenaktion geklont wird, binden sich dynamische Blöcke wie das Spendenformular, die Fortschrittsleiste und die Spenderwand zur Renderzeit immer noch an die ID der Spendenaktion. Also:

• Die Fortschrittsleiste zeigt den Fortschritt der Spendenaktion, nicht den der Vorlage.
• Das Spendenformular postet an die Kampagne der Spendenaktion.
• Die Spenderwand listet die Spender der Spendenaktion auf, nicht die der Vorlage.

Das ist es, was den visuellen Modus zum Laufen bringt – das Design wird geteilt, aber die Daten sind pro Spendenaktion.

Soziale Links

Wenn die Vorlage einen Social Links-Block enthält, wird dieser Block zu den Social-Media-Handles des Botschafters (gezogen aus seinen Benutzerprofilfeldern). Botschafter, die ihre Social-Media-Handles nicht ausgefüllt haben, erhalten einen leeren Social Links-Block – daher zeigen wir im Admin eine Warnung an, wenn Ihre Vorlage Social Links enthält, aber die Profilvervollständigung des Botschafters niedrig ist.

Welche Botschaftervorlage zeigt was

Charitable Ambassadors hat zwei Ebenen der Vorlagenkontrolle unter Botschafter → Vorlagen:

1. Frontend-Vorlagenstil — die allgemeine Engine:
   • Legacy — die ursprünglichen Vorlagen und CSS, unverändert. Die Einstellungen der Spendenaktionsseite (QR, Spenderwand, Share-Popover usw.) gelten hier nicht.
   • Erweitert — moderne Vorlagen mit Hero-Bild, Fortschrittsleiste, Icon-Statistiken, Teilen und Suchen. Empfohlen für die meisten Installationen. Die Einstellungen der Spendenaktionsseite gelten.
   • Visuell — verwenden Sie eine Kampagne, die Sie im Visual Builder erstellt haben, als Vorlage.
2. Frontend-Vorlage — wenn der Stil Erweitert ist, wählt dies das Layout aus. Jedes Layout rendert eine andere Mischung von Elementen. Verwenden Sie die folgende Tabelle, um dasjenige auszuwählen, das passt.

Vergleich der Funktionen der erweiterten Vorlage

Vorlage	QR-Code (wenn aktiviert)*	Hero-Bild	Fortschrittsleiste	Icon-Statistiken	Spenderwand	Spendenkarte	Feste Navigationsleiste	Am besten für
Klassisch	Eckaufkleber + Teilen-Popover	Ja	Ja	Ja	Ja	Rechte Seitenleiste	Nein	Ein klares, vertrautes Hero- + Story- + Spenden-Layout
Story-Fokus	Eckaufkleber + Teilen-Popover	Ja	Ja	Ja	Ja	Conversion-Band unten	Nein	Kampagnen mit Fokus auf Erzählung
Statistik-Fokus	Eckaufkleber + Teilen-Popover	Ja (kurz)	Ja	Ja	Ja	Overlay über dem Hero-Bereich	Nein	Fortschritt und Zahlen im Vordergrund
Spenden-Fokus	Eckaufkleber + Teilen-Popover	Ja (Banner)	Ja	Ja	Ja	Inline, über der Story	Nein	Maximierung von Conversions; Story zusammengeklappt
Magazin	Eckaufkleber + Teilen-Popover	Ja (filmisch)	Ja	Ja	Ja (oben oder unten)	Statistik-Band unter der Story	Nein	Redaktionelles / Premium-Gefühl
Showcase	Eckaufkleber + Teilen-Popover	Ja	Ja	Ja	Ja	Statistik-Band	Ja	Bild-Fokus, durchsuchbar (getabbt)
Showcase-Poster	Eckaufkleber + Teilen-Popover	Ja (hoch)	Ja	Ja	Ja (gestaffelt)	Inline-Band	Fester FAB	Große visuelle „Poster“-Seiten
Rally	Inline QR-Karte + Teilen-Popover	Ja	Ja	Ja	Ja	Mini-Widget (rechts)	Nein	Persönliches Teilen; QR auf der Seite hervorgehoben

* Aktivieren Sie Botschafter → Vorlagen → Spendenaktion-Seite → „QR-Code auf Spendenaktion-Seite anzeigen“ , um den QR anzuzeigen. Wenn deaktiviert, wird kein QR auf einer Vorlage angezeigt.

So erscheint der QR-Code

Wenn „QR-Code auf Spendenaktion-Seite anzeigen“ aktiviert ist, zeigt jede erweiterte Vorlage den QR-Code an, wobei die Platzierung an das jeweilige Layout angepasst ist:

• Rally zeigt den QR-Code als große Inline-Karte in der Seitenleiste an – die prominenteste Platzierung.
• Jede andere erweiterte Vorlage zeigt einen kompakten „Scan“-QR-Aufkleber , der in der oberen rechten Ecke der Spendenaktionskarte angeheftet ist.
• Alle erweiterten Vorlagen enthalten außerdem eine QR-Kachel im Teilen-Popover (klicken Sie auf Teilen → QR-Code) für ein herunterladbares PNG.

Sie müssen sich also nicht mehr nur für Rally entscheiden, um einen QR-Code zu erhalten – wählen Sie das Layout, das Ihnen am besten gefällt, und aktivieren Sie die Einstellung.

Hinweise: Das Ändern der Vorlage wirkt sich nur auf das Layout der öffentlichen Spendenaktion-Seite aus, nicht auf Ihre Daten. Wechseln Sie nach Belieben und verwenden Sie die Vorschau, um zu vergleichen. Der QR-Code ist standardmäßig deaktiviert; die Aktivierung ist eine Ein-Klick-Einstellung.

Tipps

• Beginnen Sie mit einem erweiterten Layout – in den meisten Fällen ist Visual nicht erforderlich. Verwenden Sie eine der 8 erweiterten Varianten als Ihre „gut genug“-Basis; wechseln Sie zu Visual, wenn Sie aus Sponsoren- oder Marken-Gründen maximale Kontrolle benötigen.
• Die Vorlage ist nur eine Kampagne. Sie können die Vorlage direkt in der Vorschau anzeigen – sie hat einen eigenen Permalink, genau wie jede Kampagne. Besuchen Sie die URL, während Sie abgemeldet sind, um genau zu sehen, was Botschafter sehen werden (mit den eigenen Inhalten der Vorlage, nicht ersetzt).
• Verwenden Sie Token für textlastige Inhalte. Kodieren Sie nicht fest „Hilf Sarah“ in die Vorlage – verwenden Sie Hilf {ambassador_name}, damit die Vorlage generisch bleibt.
• Platzieren Sie die Vorlage nicht in Ihrer primären Navigation. Es handelt sich um eine interne „Designquelle“, die nicht als echte Spendenaktion auffindbar sein sollte. Setzen Sie _wp_old_slug oder noindexen Sie sie.

---

Entwicklerreferenz

Der Rest dieser Seite ist für Entwickler, die den visuellen Vorlagenmodus anpassen.

Speicherung von Einstellungen

charitable_settings > ambassadors > ambassadors_ui_version          # 'legacy' | 'enhanced' | 'visual'
charitable_settings > ambassadors > p2p_template_campaign_id        # int (0 = none)
charitable_settings > ambassadors > ambassadors_enhanced_layout_variant  # used for Enhanced; informational under Visual

Helfer:

charitable_ambassadors_ui_version();                                // 'legacy' | 'enhanced' | 'visual'
charitable_ambassadors_should_use_p2p_template( $fundraiser_id );   // bool
charitable_ambassadors_substitute_p2p_tokens( $string, $fundraiser_id ); // string
charitable_ambassadors_fundraiser_template_is_theme_overridden();   // bool

Substitutions-Gate

Die Substitution wird nur ausgelöst, wenn ALLE folgenden Bedingungen erfüllt sind:

1. ambassadors_ui_version === 'visual'.
2. p2p_template_campaign_id > 0.
3. Der angeforderte Beitrag ist eine veröffentlichte Spendenaktion (ein Kind einer Peer-to-Peer-fähigen übergeordneten Kampagne).
4. Die Spendenaktion ist NICHT die Vorlage selbst.
5. Die Spendenaktion hat keine eigenen campaign_settings_v2 Metadaten (roher $wpdb-Check, um Filterrekursion zu vermeiden).
6. Die Vorlage hat campaign_settings_v2 Metadaten.
7. Die Anfrage ist kein Admin-Kontext (damit der visuelle Builder die Metadaten einer Spendenaktion normal bearbeiten kann).

Wenn ein Gate falsch ist, ist die Substitution eine No-Operation und Pro liest die eigenen Metadaten der Spendenaktion (oder greift auf das Legacy-Rendering zurück).

Der Ersetzungshaken

add_filter( 'get_post_metadata', [ self::class, 'maybe_substitute_p2p_template' ], 10, 4 );

Der Filter-Handler:

1. Kehrt frühzeitig bei den obigen Toren zurück.
2. Liest die campaign_settings_v2-Metadaten der Vorlage direkt über $wpdb (keine Filterrekursion).
3. Klont die Daten tief, schreibt id/title neu.
4. Durchläuft rekursiv jedes String-Blatt und führt jedes durch den Token-Substitutionsdienst.
5. Gibt das geklonte und substituierte Array zurück, als ob es die Metadaten des Spendenwerbers wären.

Filter

Filter	Standard	Zweck
charitable_ambassadors_p2p_template_tokens	Array von 9	Fügt benutzerdefinierte Tokens zum Substitutionsdienst hinzu. Empfängt ($tokens, $fundraiser_id).
charitable_ambassadors_should_use_p2p_template	berechneter bool	Erzwingt die Aktivierung oder Deaktivierung der Ersetzung für einen bestimmten Spendenwerber. Empfängt ($should, $fundraiser_id).
charitable_ambassadors_p2p_template_campaign_id	Einstellungswert	Überschreibt die Vorlagen-ID zur Laufzeit (z. B. für eine Vorlage pro Elternteil).
charitable_ambassadors_onboarding_visual_template_candidates	berechnet	Welche Kampagnen im Admin-Auswahl-Autocomplete angezeigt werden.

Aktionen

Aktion	Argumente	Wird ausgelöst, wenn
charitable_ambassadors_p2p_template_applied	$fundraiser_id, $template_id	Ersetzung für ein Spendenwerber-Rendering bestätigt.

Token-Registrierung

add_filter( 'charitable_ambassadors_p2p_template_tokens', function ( $tokens, $fundraiser_id ) {
    $author = get_user_by( 'id', get_post_field( 'post_author', $fundraiser_id ) );
    $tokens['{ambassador_city}'] = $author ? (string) get_user_meta( $author->ID, 'billing_city', true ) : '';
    return $tokens;
}, 10, 2 );

Funktionen

Zugriff auf Einstellungen: manage_charitable_settings. Das Rendern im Frontend hat kein Berechtigungstor.

Kompatibilität

Wenn eine Pro-Version älter als die Unterstützung für den Kampagnen-Builder aktiv ist, wird der Auswähler eingeschränkt und der visuelle Modus fällt auf das erweiterte Rendering zurück. Die Prüfung wird in charitable_ambassadors_visual_mode_is_available() implementiert.

Anpassungsbeispiele

Verwenden Sie eine Vorlage pro Elternteil (jede Elternkampagne hat ihre eigene Vorlage):

add_filter( 'charitable_ambassadors_p2p_template_campaign_id', function ( $template_id ) {
    $fundraiser_id = get_the_ID();
    $parent_id     = (int) get_post_meta( $fundraiser_id, '_campaign_parent', true );
    if ( $parent_id ) {
        $per_parent = (int) get_post_meta( $parent_id, '_ambassadors_template_campaign_id', true );
        if ( $per_parent > 0 ) {
            return $per_parent;
        }
    }
    return $template_id;
} );

Fügen Sie ein {donate_url}-Token hinzu:

add_filter( 'charitable_ambassadors_p2p_template_tokens', function ( $tokens, $fundraiser_id ) {
    $tokens['{donate_url}'] = add_query_arg( 'donate', '1', get_permalink( $fundraiser_id ) );
    return $tokens;
}, 10, 2 );

Überspringen Sie den visuellen Modus für Spendenwerber in einem bestimmten Begriff (z. B. Legacy-Migration):

add_filter( 'charitable_ambassadors_should_use_p2p_template', function ( $should, $fundraiser_id ) {
    if ( has_term( 'legacy-migration', 'campaign_tag', $fundraiser_id ) ) {
        return false;
    }
    return $should;
}, 10, 2 );

Beschränken Sie die Vorlagenauswahl auf eine bestimmte Kategorie:

add_filter( 'charitable_ambassadors_onboarding_visual_template_candidates', function ( $candidates ) {
    return array_filter( $candidates, function ( $candidate ) {
        return has_term( 'p2p-templates', 'campaign_category', $candidate['id'] );
    } );
} );

Verwandt

• Spendenwerber-Seite – der Layout-Auswähler, der verwendet wird, wenn der visuelle Modus nicht aktiv ist.
• Layout-Varianten – die 8 integrierten Varianten, die vom erweiterten Modus verwendet werden.
• Funktionen anzeigen – die Ausrichtung des Tabs "Vorlagen".
• Theming – die primäre Akzentfarbe fließt auch in den visuellen Modus ein.
• Hooks & Filter in Ambassadors – vollständige Referenz.