Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Le Mode de modèle visuel vous permet de concevoir une seule campagne à l'aide du générateur de campagnes visuelles de Charitable – faites glisser des blocs, définissez la typographie, placez un mur de donateurs, ajoutez une bande de sponsors.

Ensuite, vous pouvez faire en sorte que chaque levée de fonds d'ambassadeur hérite de cette conception, personnalisée pour chaque ambassadeur.

• Leur nom là où se trouvent les espaces réservés.
• Leur histoire là où se trouve le bloc d'histoire du modèle.
• Leur image là où se trouve l'image principale du modèle.
• Leur progression par rapport à leur objectif là où se trouve la barre de progression du modèle.

C'est la différence entre chaque levée de fonds qui se ressemble (ennuyeux) et chaque levée de fonds qui semble cohérente (conforme à la marque). Le modèle est la couche de marque ; le contenu de l'ambassadeur remplit les détails.

Quand l'utiliser

• Événements sponsorisés – le sponsor de niveau or du marathon souhaite que son logo apparaisse sur la page de chaque ambassadeur. Le modèle transporte le bloc de logo ; chaque levée de fonds en hérite.
• Programmes de marque stricts – votre équipe d'identité visuelle souhaite un contrôle strict sur la façon dont chaque page est rendue. Concevez-la une fois ; verrouillez-la.
• Tests A/B – clonez le modèle, modifiez la copie, échangez le modèle actif ; chaque levée de fonds est échangée en temps réel.
• Causes cinématographiques – campagnes commémoratives, levées de fonds de gala – le même héros, la même palette de couleurs, le même rythme émotionnel à travers chaque ambassadeur.

Trouver les modèles visuels

Dans votre administration WordPress, allez à Charitable » Ambassadeurs » Modèles

L'onglet sous-jacent Modèles contient trois groupes de paramètres :

1. Style de modèle frontal – le sélecteur Hérité / Amélioré / Visuel. C'est ici que vous activez le mode Visuel.
2. Campagne de modèle de levée de fonds – le sélecteur de campagne qui choisit quelle campagne existante agit comme modèle. Affiché uniquement lorsque Visuel est sélectionné.
3. Modèle frontal – le sélecteur de variante de mise en page (identique à l'onglet sous-jacent Page de levée de fonds). Lorsqu'une campagne modèle est configurée, ceci est uniquement informatif – le modèle l'emporte.

Choisir un style de modèle frontal

Trois modes, chacun progressivement plus performant :

Mode	Rend les pages de levée de fonds avec…
Hérité	Les modèles originaux 1.x. CSS et balisage inchangés. Choisissez ceci si vous avez personnalisé des modèles ou du CSS et que vous ne voulez rien changer.
Amélioré	Les modèles 3.0 (barres de progression, statistiques d'icônes, fenêtre contextuelle de partage, recherche) par-dessus les pages existantes. Utilise le sélecteur de mise en page de la page de levée de fonds pour la forme.
Visuel	Chaque page de levée de fonds est rendue à partir d'une mise en page du générateur de campagnes visuelles que vous choisissez ci-dessous. Contrôle maximal.

Vous pouvez passer d'un mode à l'autre à tout moment. Revenir à Hérité ne perd aucune des configurations enregistrées – le pointeur de campagne modèle du mode Visuel est préservé afin que vous puissiez y revenir plus tard.

Choisir une campagne modèle

Une fois Visuel sélectionné, le sélecteur Campagne de modèle de levée de fonds apparaît.

Le sélecteur est piloté par autocomplétion – commencez à taper le titre de votre modèle, choisissez parmi les résultats. Il ne propose que les campagnes qui :

• Ont été ouverts dans le Générateur de campagnes visuelles (ont des métadonnées post-rendu campaign_settings_v2).
• Ne sont pas la collecte de fonds que vous êtes sur le point de rendre (pas de boucle infinie).
• Passent tous les filtres charitable_ambassadors_onboarding_visual_template_candidates que vous avez ajoutés.

Choisissez-en un, enregistrez, et le mode Visuel est actif. Chaque collecte de fonds d'ambassadeur sur votre site est désormais rendue en utilisant la conception de cette campagne.

Comment fonctionne la substitution

Lorsqu'un visiteur charge une page de collecte de fonds d'ambassadeur, Ambassadeurs intercepte le filtre get_post_metadata pour la clé de métadonnées campaign_settings_v2 de la campagne. Voici ce qui se passe :

1. Pro demande les données du constructeur campaign_settings_v2 de la collecte de fonds.
2. Ambassadeurs vérifie : sommes-nous en mode Visuel ? Un modèle est-il configuré ? S'agit-il d'une page de collecte de fonds (pas du modèle lui-même) ? Cette collecte de fonds a-t-elle ses propres données de constructeur (si oui, les données propres à la collecte de fonds priment) ?
3. Si toutes les conditions sont remplies, Ambassadeurs clone en profondeur le campaign_settings_v2 du modèle, réécrit id à l'ID de la collecte de fonds et title au titre de la collecte de fonds.
4. Chaque chaîne de caractères dans les données clonées est traitée par le substituteur de jetons – tout {ambassador_name}, {parent_title}, {percent_raised}, etc. est remplacé par les valeurs réelles de la collecte de fonds.
5. Pro lit les données substituées et rend. Chaque bloc dynamique (formulaire-don, barre-progression, mur-donateurs) se re-lie à l'ID de la collecte de fonds au moment du rendu.

Le résultat : une page de collecte de fonds qui ressemble exactement au modèle, mais avec le contenu du bon ambassadeur.

Jetons disponibles

Vous pouvez utiliser n'importe lequel de ces jetons dans les champs de texte, le texte alternatif, les légendes, etc. du modèle :

Jeton	Substitué par
{title}	Le titre de la publication de la collecte de fonds.
{ambassador_name}	Le nom d'affichage de l'auteur.
{parent_title}	Le titre de la campagne parente.
{parent_url}	Le permalien de la campagne parente.
{goal}	Le montant de l'objectif de la collecte de fonds (formaté).
{raised}	Le montant collecté pour la collecte de fonds (formaté).
{donor_count}	Le nombre de donateurs uniques.
{percent_raised}	Progression en pourcentage (par exemple, 42 %).
{fundraiser_image}	URL de l'image mise en avant.

Insérez-les n'importe où dans le contenu textuel du modèle. Par exemple, un titre principal « Aidez {ambassador_name} à atteindre son objectif de {goal} » devient « Aidez Sarah Chen à atteindre son objectif de 5 000 $ » sur la campagne de Sarah, « Aidez Marcus Liu à atteindre son objectif de 2 500 $ » sur celle de Marcus.

Remplacements par campagne

Une campagne peut se désengager du modèle en ayant ses propres métadonnées campaign_settings_v2. Si vous (ou l'ambassadeur) ouvrez une campagne spécifique dans le Générateur de campagnes visuelles et l'enregistrez, les données de cette campagne priment désormais – le modèle ne s'y applique plus.

Pour restaurer le design du modèle sur une campagne qui a suivi sa propre voie : supprimez les métadonnées campaign_settings_v2 de cette campagne :

delete_post_meta( $fundraiser_id, 'campaign_settings_v2' );

Le prochain chargement de page réappliquera le modèle.

Les blocs dynamiques fonctionnent toujours

Même si la structure du modèle est clonée pour chaque campagne, les blocs dynamiques comme le formulaire de don, la barre de progression et le mur des donateurs sont toujours liés à l'identifiant de la campagne au moment du rendu. Donc :

• La barre de progression affiche la progression de la campagne, pas celle du modèle.
• Le formulaire de don publie sur la campagne de la campagne.
• Le mur des donateurs liste les donateurs de la campagne, pas ceux du modèle.

C'est ce qui fait fonctionner le mode Visuel – le design est partagé, mais les données sont par campagne.

Liens sociaux

Si le modèle inclut un bloc de liens sociaux, ce bloc devient les identifiants sociaux de l'ambassadeur (tirés de ses champs de profil utilisateur). Les ambassadeurs qui n'ont pas rempli leurs identifiants sociaux obtiennent un bloc de liens sociaux vide – nous affichons donc un avertissement dans l'administration si votre modèle inclut des liens sociaux mais que le taux de complétion du profil de l'ambassadeur est faible.

Quel modèle d'ambassadeur affiche quoi

Les ambassadeurs caritatifs ont deux niveaux de contrôle de modèle sous Ambassadeurs → Modèles :

1. Style de modèle frontal — le moteur général :
   • Hérité — les modèles et CSS d'origine, inchangés. Les paramètres de la page de campagne (QR, mur des donateurs, popover de partage, etc.) ne s'appliquent pas ici.
   • Amélioré — modèles modernes avec image principale, barre de progression, statistiques d'icônes, partage et recherche. Recommandé pour la plupart des installations. Les paramètres de la page de campagne s'appliquent.
   • Visuel — utilisez une campagne que vous avez créée dans le Générateur visuel comme modèle.
2. Modèle frontal — lorsque le style est Amélioré, ceci choisit la mise en page. Chaque mise en page rend un mélange différent d'éléments. Utilisez le tableau ci-dessous pour choisir celui qui convient.

Comparaison des fonctionnalités des modèles améliorés

Modèle	Code QR (lorsqu'il est activé)*	Image principale	Barre de progression	Statistiques d'icônes	Mur des donateurs	Carte de don	Navigation fixe	Idéal pour
Classique	Autocollant d'angle + Pop-up de partage	Oui	Oui	Oui	Oui	Barre latérale droite	Non	Une mise en page héros + histoire + don claire et familière
Histoire d'abord	Autocollant d'angle + Pop-up de partage	Oui	Oui	Oui	Oui	Bande de conversion en bas	Non	Campagnes axées sur le récit
Statistiques d'abord	Autocollant d'angle + Pop-up de partage	Oui (court)	Oui	Oui	Oui	Superposition sur le héros	Non	Mettre en avant les progrès et les chiffres
Don d'abord	Autocollant d'angle + Pop-up de partage	Oui (bannière)	Oui	Oui	Oui	En ligne, au-dessus de l'histoire	Non	Maximiser les conversions ; histoire réduite
Magazine	Autocollant d'angle + Pop-up de partage	Oui (cinématique)	Oui	Oui	Oui (en haut ou en bas)	Bande de statistiques sous l'histoire	Non	Ambiance éditoriale / premium
Vitrine	Autocollant d'angle + Pop-up de partage	Oui	Oui	Oui	Oui	Bande de statistiques	Oui	Image d'abord, consultable (par onglets)
Affiche de vitrine	Autocollant d'angle + Pop-up de partage	Oui (grand)	Oui	Oui	Oui (à plusieurs niveaux)	Bande en ligne	FAB fixe	Pages visuelles « poster »
Rassemblement	Carte QR intégrée + Pop-up de partage	Oui	Oui	Oui	Oui	Mini widget (droite)	Non	Partage en personne ; QR présenté sur la page

* Activez Ambassadeurs → Modèles → Page de collecte de fonds → « Afficher le code QR sur la page de collecte de fonds » pour afficher le QR. S’il est désactivé, aucun QR n’apparaît sur aucun modèle.

Comment le code QR apparaît

Avec « Afficher le code QR sur la page de collecte de fonds » activé, chaque modèle amélioré affiche le QR, avec un placement adapté à sa mise en page :

• Rally présente le QR sous forme de grande carte intégrée dans la barre latérale — le placement le plus proéminent.
• Tous les autres modèles améliorés affichent un autocollant QR « Scanner » compact épinglé dans le coin supérieur droit de la carte de collecte de fonds.
• Tous les modèles améliorés incluent également une tuile QR dans le pop-up de partage (cliquez sur Partager → Code QR) pour un PNG téléchargeable.

Vous n’avez donc plus besoin de choisir Rally juste pour obtenir un QR — choisissez la mise en page que vous préférez et activez le paramètre.

Remarques : Changer le modèle n’affecte que la mise en page de la page de collecte de fonds publique, pas vos données. Changez librement et utilisez Aperçu pour comparer. Le QR est désactivé par défaut ; l’activer est un réglage en un clic.

Conseils

• Commencez avec une mise en page améliorée – la plupart des cas n’ont pas besoin de Visual. Utilisez l’une des 8 variantes améliorées comme base « suffisamment bonne » ; passez à Visual lorsque vous avez un sponsor ou une raison de marque qui nécessite un contrôle maximal.
• Le modèle n’est qu’une campagne. Vous pouvez prévisualiser le modèle directement – il a son propre permalien, comme n’importe quelle campagne. Visitez l’URL en étant déconnecté pour voir exactement ce que les ambassadeurs verront (avec le propre contenu du modèle, non substitué).
• Utilisez des jetons pour tout ce qui est lourd en texte. Ne codez pas en dur « Aidez Sarah » dans le modèle – utilisez Aidez {ambassador_name} pour que le modèle reste générique.
• Ne mettez pas le modèle dans votre navigation principale. C’est une « source de conception » interne qui ne doit pas être trouvable comme une vraie collecte de fonds. Définissez _wp_old_slug ou indexez-la en noindex.

---

Référence développeur

Le reste de cette page est destiné aux développeurs qui personnalisent le mode de modèle visuel.

Stockage des paramètres

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

Aides :

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

Porte de substitution

La substitution ne s'active que si TOUTES ces conditions sont vraies :

1. ambassadeurs_ui_version === 'visuel'.
2. p2p_template_campaign_id > 0.
3. La publication demandée est une collecte de fonds publiée (un enfant d'un parent activé pour le P2P).
4. La collecte de fonds n'est PAS le modèle lui-même.
5. La collecte de fonds n'a pas de métadonnées campaign_settings_v2 propres (vérification brute de $wpdb pour éviter la récursion des filtres).
6. Le modèle a des métadonnées campaign_settings_v2.
7. La requête n'est pas dans un contexte d'administration (afin que le Visual Builder puisse modifier normalement les métadonnées d'une collecte de fonds).

Si une porte est fausse, la substitution est une opération nulle et Pro lit les métadonnées propres de la collecte de fonds (ou revient au rendu hérité).

Le hook de substitution

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

Le gestionnaire de filtre :

1. Retourne tôt sur les portes ci-dessus.
2. Lit les métadonnées campaign_settings_v2 du modèle directement via $wpdb (pas de récursion de filtre).
3. Duplique profondément les données, réécrit id/title.
4. Parcourt récursivement chaque feuille de chaîne et exécute chacune via le substitut de jeton.
5. Retourne le tableau cloné et substitué comme s'il s'agissait des métadonnées du collecteur de fonds.

Filtres

Filtre	Défaut	Objectif
charitable_ambassadors_p2p_template_tokens	tableau de 9	Ajoute des jetons personnalisés au substitut. Reçoit ($tokens, $fundraiser_id).
charitable_ambassadors_should_use_p2p_template	booléen calculé	Force l'activation ou la désactivation de la substitution pour un collecteur de fonds spécifique. Reçoit ($should, $fundraiser_id).
charitable_ambassadors_p2p_template_campaign_id	valeur du paramètre	Remplace l'ID du modèle à la volée (par exemple, pour un modèle par parent).
charitable_ambassadors_onboarding_visual_template_candidates	calculé	Quelles campagnes apparaissent dans l'autocomplétion du sélecteur d'administration.

Actions

Action	Args	Se déclenche lorsque
charitable_ambassadors_p2p_template_applied	$fundraiser_id, $template_id	Substitution validée pour le rendu d'un collecteur de fonds.

Registre des jetons

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 );

Capacités

Accès aux paramètres : manage_charitable_settings. Le rendu côté client n'a pas de porte de capacité.

Compatibilité

Lorsqu'une version Pro antérieure au support du constructeur de campagne est active, le sélecteur est limité et le mode visuel se rabat sur le rendu amélioré. La vérification est implémentée dans charitable_ambassadors_visual_mode_is_available().

Exemples de personnalisation

Utiliser un modèle par parent (chaque campagne parente a son propre modèle) :

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;
} );

Ajouter un jeton {donate_url} :

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 );

Ignorer le mode visuel pour les collecteurs de fonds dans un terme spécifique (par exemple, migration héritée) :

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 );

Restreindre le sélecteur de modèles à une catégorie spécifique :

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'] );
    } );
} );

Connexes

• Page du collecteur de fonds – le sélecteur de mise en page utilisé lorsque le mode visuel n'est pas actif.
• Variantes de mise en page – les 8 variantes intégrées utilisées par Enhanced.
• Afficher les fonctionnalités – l’orientation de l’onglet Modèles.
• Thèmes – la couleur d’accentuation principale s’écoule également en mode Visuel.
• Hooks & filtres dans Ambassadors – référence complète.