Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+
La carte Recruter des collecteurs de fonds se trouve en haut de la page Mes campagnes d'un ambassadeur éligible. Elle affiche son URL d'invitation personnelle, des boutons de partage, une ligne de statistiques et un interrupteur "Vos recrues" – et c'est la surface la plus personnalisée dans Ambassadeurs car chaque programme souhaite placer un message légèrement différent avant le lien de recrutement.
Cette page est la référence pour les filtres et les actions qui vous permettent de personnaliser la carte de recrutement sans avoir à modifier le modèle.
Où elle se trouve
La carte s'affiche dans l'action charitable_ambassadors_my_campaigns_before_grid – en d'autres termes, juste avant la grille de campagne de la page [charitable_my_campaigns].
Son chemin de modèle : templates/invite/recruit-card.php. Chemin de remplacement de thème : your-theme/charitable-pro/charitable-ambassadors/invite/recruit-card.php.
La personnalisation la plus courante : Lien En savoir plus
Par défaut, la carte n'a pas de lien En savoir plus – nous laissons l'emplacement vide afin que les sites qui n'en ont pas besoin restent épurés. Pour l'activer, définissez à la fois l'URL et (facultativement) l'étiquette :
add_filter( 'charitable_ambassadors_recruit_card_learn_more_url', function () {
return home_url( '/ambassador-handbook/recruiting/' );
} );
add_filter( 'charitable_ambassadors_recruit_card_learn_more_label', function () {
return 'Tips for inviting friends';
} );
Le lien s'affiche en ligne en bas de la carte avec une cible de lien externe (il s'ouvre donc dans un nouvel onglet sans perdre la position de l'utilisateur).
Si l'URL est vide (par défaut), l'emplacement est entièrement supprimé – pas de placeholder vide.
Injecter du contenu personnalisé (hook de pied de page)
Pour *plus* qu'un simple lien – un court argumentaire, un embed vidéo, un widget "voir les meilleurs recruteurs de la semaine" – utilisez l'action de pied de page :
add_action( 'charitable_ambassadors_recruit_card_footer', function ( $user_id, $token, $invite_url ) {
echo '<p class="recruit-card-tip">Pro tip: share with two people who would care about this cause.</p>';
echo '<a class="button" href="https://example.com/recruit-video">Watch the 2-minute guide</a>';
}, 10, 3 );
L'action s'exécute juste au-dessus de l'emplacement "En savoir plus". Votre rappel est responsable de sa propre mise en échappement.
Éligibilité – contrôler qui voit la carte
La carte ne s'affiche que pour les utilisateurs qui sont *éligibles pour recruter*. Ceci est défini par le filtre charitable_ambassadors_user_can_invite :
add_filter( 'charitable_ambassadors_user_can_invite', function ( $can, $user_id, $campaign_id_or_null ) {
// Only verified ambassadors can recruit.
if ( '1' !== get_user_meta( $user_id, '_charitable_ambassadors_verified', true ) ) {
return false;
}
return $can;
}, 10, 3 );
Le filtre est global – il contrôle à la fois la carte Mes campagnes, les popovers de recrutement par campagne ET l'aperçu "voir en tant que recruteur" de l'administrateur.
Pour remplacer spécifiquement la visibilité de la carte (sans affecter d'autres surfaces), filtrez charitable_ambassadors_show_recruit_card :
add_filter( 'charitable_ambassadors_show_recruit_card', function ( $show, $user_id ) {
// Hide the card on Mondays. Don't ask.
return $show && 'Mon' !== gmdate( 'D' );
}, 10, 2 );
Personnaliser le texte d'état vide
Lorsqu'un recruteur n'a encore aucune recrue, la ligne de statistiques de la carte affiche une invite douce "pas encore de recrues". Personnalisez cela :
add_filter( 'charitable_ambassadors_recruit_card_empty_text', function () {
return 'No recruits yet - your link is ready when you are.';
} );
Filtre miroir pour l'état vide de la vue Vos recrues :
add_filter( 'charitable_ambassadors_recruits_view_empty_text', function ( $message, $status, $user_id ) {
if ( 'rejected' === $status ) {
return 'No rejected recruits - your standards are solid!';
}
return $message;
}, 10, 3 );
Classe du corps
La carte a sa propre classe limitée pour le CSS :
.charitable-ambassadors-recruit-card
Placez vos remplacements sous ce sélecteur. La carte respecte la Couleur d'accentuation principale via --cap-accent.
Conseils
- Ajoutez un lien "En savoir plus". C'est un gain facile – même un manuel interne d'une page vaut mieux qu'aucun lien.
- Gardez le pied de page concis. La carte est destinée à être un appel à l'action tactile, pas une conférence. Une courte ligne, un bouton.
- Testez sur mobile. Les URL longues ou les boutons larges peuvent déborder de la carte sur les vues étroites.
- Filtrer l'éligibilité aux programmes spéciaux. « Seuls les ambassadeurs vérifiés peuvent recruter » est une politique à fort effet de levier.
Référence du développeur
Filtres
| Filtre | Défaut | Objectif |
|---|---|---|
charitable_ambassadors_recruit_card_learn_more_url | '' | URL du lien « En savoir plus ». Laisser vide supprime le lien. |
charitable_ambassadors_recruit_card_learn_more_label | « En savoir plus » | Texte de l'étiquette. |
charitable_ambassadors_recruit_card_empty_text | calculé | Texte d'état vide lorsqu'il n'y a aucun recrutement. |
charitable_ambassadors_recruits_view_empty_text | calculé | Texte d'état vide dans l'onglet Vos recrutements. Reçoit ($message, $status, $user_id). |
ambassadeurs_caritatifs_afficher_carte_recruter | calculé | Masquage spécifique à la carte. Reçoit ($show, $user_id). |
charitable_ambassadors_user_can_invite | calculé | Vérification d'éligibilité sous-jacente. Reçoit ($can, $user_id, $campaign_id). |
ambassadeurs_caritatifs_carte_recruter_partager_reseaux | paramètre du site | Remplace les réseaux de partage qui apparaissent sur la carte. |
Actions
| Action | Args | Se déclenche lorsque |
|---|---|---|
charitable_ambassadors_recruit_card_footer | $user_id, $token, $invite_url | Dans la carte, juste au-dessus du lien En savoir plus. |
ambassadeurs_caritatifs_carte_recruter_avant | $user_id | Juste avant le début du balisage de la carte. |
ambassadeurs_caritatifs_carte_recruter_apres | $user_id | Juste après la fin du balisage de la carte. |
Pop-up Recruter par campagne
Les propriétaires de campagnes parentes obtiennent également un bouton Recruter par campagne dans la ligne d'action de chaque campagne. La pop-up qui s'ouvre a sa propre action :
add_action( 'charitable_ambassadors_recruit_popover_footer', function ( $campaign_id, $user_id, $token, $invite_url ) {
echo '<p>Sharing this link recruits for "' . esc_html( get_the_title( $campaign_id ) ) . '" specifically.</p>';
}, 10, 4 );
Chemin du modèle
templates/invite/recruit-card.php # the My Campaigns recruit card
templates/invite/recruit-card-popover.php # the per-campaign recruit popover
Chemin de remplacement du thème : your-theme/charitable-pro/charitable-ambassadors/invite/recruit-card.php.
Capacités
Rendu public – la carte décide par utilisateur s'il faut l'afficher via le filtre d'éligibilité. Pas de porte de capacité.
Exemples de personnalisation
Masquer la carte aux administrateurs (seuls les ambassadeurs devraient la voir) :
add_filter( 'charitable_ambassadors_show_recruit_card', function ( $show, $user_id ) {
$user = get_user_by( 'id', $user_id );
if ( $user && user_can( $user, 'administrator' ) ) {
return false;
}
return $show;
}, 10, 2 );
Ajouter un bouton « Copier le message court » à la carte :
add_action( 'charitable_ambassadors_recruit_card_footer', function ( $user_id, $token, $invite_url ) {
$msg = 'Help me fundraise for this cause! ' . $invite_url;
echo '<button class="button" type="button" data-clipboard-text="' . esc_attr( $msg ) . '">Copy short message</button>';
}, 10, 3 );
Afficher une variante de carte différente pour un rôle utilisateur spécifique :
add_filter( 'charitable_ambassadors_recruit_card_template', function ( $template, $user_id ) {
if ( user_can( $user_id, 'verified_ambassador' ) ) {
return 'recruit-card-verified.php'; // your custom partial
}
return $template;
}, 10, 2 );
Restreindre les réseaux de partage affichés sur la carte à Copier le lien + E-mail uniquement :
add_filter( 'charitable_ambassadors_recruit_card_share_networks', function () {
return [ 'email', 'copy' ];
} );
Connexes
- Invitations – le document de la fonctionnalité parente.
- Mes campagnes – où se trouve la carte.
- Thèmes – la couleur d’accentuation que la carte respecte.
- Réseaux de partage – le catalogue des réseaux.
- Hooks & filtres dans Ambassadors – référence complète.
