Flux de dons

Le Flux de dons affiche une liste en direct et déroulante des dons récents sur n'importe quelle page ou publication – vous aidant à renforcer la transparence, à inspirer les visiteurs et à créer une preuve sociale pour vos campagnes. Il est disponible avec le plugin Charitable Pro 1.8.13+.

Disponible en tant que shortcode et bloc Gutenberg, le Flux de dons est entièrement personnalisable : choisissez entre une vue liste/tableau ou une grille de cartes, contrôlez précisément les informations du donateur affichées, appliquez des thèmes de couleurs et activez la pagination AJAX – le tout sans toucher une ligne de code.

Table des matières

Fonctionnalités clés
Pourquoi utiliser un flux de dons ?
Cas d'utilisation
Voyez-le en action
Démarrage
Méthodes d'utilisation
Référence complète des paramètres
Exemples
Personnalisation
Filtres et Hooks WordPress
Dépannage
FAQ
Ressources supplémentaires
Journal des modifications

Fonctionnalités clés

Tout d'abord, vous obtenez deux types de vues – la vue liste et la vue tableau avec en-têtes de colonnes, et une grille de cartes réactive – basculable avec un seul réglage.

Vues de liste de cartes dans le flux de dons | Charitable

Les autres fonctionnalités incluent :

Options d'affichage flexibles : Affichez ou masquez les avatars, le prénom, le nom, le montant du don, la date, le commentaire, le nom de la campagne et la localisation du donateur indépendamment.
Filtrage intelligent : Filtrez par campagne, plage de dates (y compris des dates personnalisées de/à), montant minimum, recherche par nom de donateur ou une liste spécifique d'identifiants de dons.
Regroupement des donateurs : Regroupez éventuellement plusieurs dons du même donateur en une seule entrée montrant leur total, avec un badge « Total ».
Pagination AJAX : Pages numérotées ou bouton Charger plus – tous deux entièrement pilotés par AJAX sans rechargement de page.
Basculement de l'en-tête du tableau : Masquez éventuellement la ligne d'en-tête de colonne en vue liste pour un aspect intégré plus épuré.
Thèmes de couleurs : Sept contrôles de couleurs indépendants (primaire/accent, montant, bordure, arrière-plan de ligne alternée, arrière-plan au survol, en-tête, texte secondaire).
Taille de police et alignement des cartes : Mise à l'échelle de la taille de police par bloc et alignement des cartes à gauche/au centre/à droite pour la grille de cartes.
Localisation du donateur : Affichez la ville, l'état et/ou le pays sous le nom du donateur – chaque champ est activé individuellement.
Support des dons anonymes : Les dons anonymes affichent un nom et un avatar de remplacement ; include_anonymous contrôle s'ils apparaissent ou non.
Hooks de filtre pour développeurs : Neuf hooks apply_filters() tout au long du pipeline de requête, de données, d'affichage et de sortie pour une personnalisation complète par les développeurs.

Pourquoi utiliser un flux de dons ?

Un flux de dons montre aux visiteurs que de vraies personnes donnent – en ce moment même. Ce type de preuve sociale peut augmenter significativement les conversions sur les pages de campagne et de collecte de fonds.

Transparence : Laissez les supporters voir l'impact de la communauté qui les entoure.
Preuve sociale : Voir un flux de dons récents encourage les visiteurs hésitants à donner.
Reconnaissance : Les donateurs apprécient de savoir que leur contribution a été reconnue publiquement.
Engagement : Un flux en direct sur une page d'accueil ou de campagne maintient le contenu frais et actif.
Confiance : Une activité visible des donateurs signale que votre organisation est active et bien soutenue.

Cas d'utilisation

Affichez les dons récents sur une page spécifique à une campagne pour montrer la dynamique.
Intégrez un flux sur tout le site sur la page d'accueil pour célébrer toute votre communauté de donateurs.
Affichez un flux filtré des dons supérieurs à un certain montant pour mettre en évidence les dons majeurs.
Utilisez la vue carte dans une barre latérale ou une zone de widget pour un effet compact de « mur des donateurs ».
Utilisez donation_ids pour choisir manuellement des dons spécifiques pour une vitrine organisée.
Utilisez groupby_donor pour créer un rouleau de donateurs simplifié qui montre les totaux plutôt que les transactions individuelles.
Affichez le flux anonymement (avec show_first_name=0 show_last_name=0) pour les campagnes soucieuses de la vie privée.

Voyez-le en action

Une vidéo sera bientôt publiée ici – revenez bientôt !

Démarrage

Exigences

Charitable Pro (version 1.8.13 ou ultérieure)
WordPress 6.2 ou ultérieure
PHP 7.4 ou version ultérieure

Activation

Le shortcode et le bloc Donations Feed sont automatiquement disponibles dès l'activation de Charitable Pro – aucune étape supplémentaire n'est requise. La balise du shortcode est [charitable_donations_feed] et le bloc apparaît dans l'éditeur de blocs sous la catégorie Widgets sous le nom de Donations Feed.

Méthodes d'utilisation

Raccourci

Ajoutez le shortcode à n'importe quelle page, article, widget ou fichier de modèle :

[charitable_donations_feed]

Ceci affiche le flux avec tous les paramètres par défaut – vue liste, 10 dons les plus récents, tous les champs affichés.

Exemple de base avec des options courantes :

[charitable_donations_feed view="card" number="12" cards_per_row="4" orderby="amount"]

Filtrage sur une campagne spécifique :

[charitable_donations_feed campaign="42" number="5" show_campaign="0"]

Utilisation dans un modèle PHP :

echo do_shortcode( '[charitable_donations_feed view="list" number="20" pagination="on"]' );

Bloc Gutenberg WordPress

Ouvrez l'éditeur de blocs WordPress sur n'importe quelle page ou article.
Cliquez sur l'outil d'insertion + et recherchez Donations Feed.
Cliquez sur le bloc pour l'insérer. Un aperçu côté serveur en direct s'affiche immédiatement.
Ouvrez le panneau des paramètres du bloc (panneau de droite) pour configurer toutes les options :
- Panneau Contenu – Type de vue, titre, description, nombre de dons et cartes par ligne (vue carte uniquement).
- Panneau Filtres – Campagne, trier par, ordre, plage de dates, montant minimum, recherche par nom de donateur et identifiants de dons spécifiques.
- Panneau Champs d'affichage – Activer/désactiver la visibilité de l'en-tête du tableau, de l'avatar, du prénom/nom, du montant, de la date, des commentaires, du nom de la campagne, de l'emplacement (avec des sous-options ville/état/pays).
- Panneau Pagination – Activer la pagination et choisir entre des pages numérotées ou un bouton Charger plus.
- Panneau Style – Couleurs alternées des lignes, taille de la police et alignement des cartes.
- Panneau Couleurs – Sept sélecteurs de couleurs individuels pour un contrôle complet du thème.

L'aperçu du bloc se met à jour en temps réel à mesure que vous modifiez les paramètres dans la barre latérale.

Référence complète des paramètres

Note : Tous les paramètres booléens acceptent 1 / 0, true / false, yes / no, ou on / off.

Paramètres principaux

vue

Type : Chaîne de caractères
Par défaut : liste
Options : list | card
Description : Contrôle la mise en page globale. list affiche un tableau réactif avec des en-têtes de colonne. card affiche une grille CSS de cartes de dons individuelles.
Exemple : view="card"

nombre

Type : Entier
Par défaut : 10
Description : Le nombre maximum de dons à afficher par page. Lorsque la pagination est activée, c'est le nombre affiché par page.
Exemple : number="20"

cartes par ligne

Type : Entier
Par défaut : 3
Description : S'applique uniquement lorsque view="card". Définit le nombre de colonnes dans la grille de cartes. Sur les écrans de tablette (≤900px), la grille se réduit automatiquement à 2 colonnes ; sur mobile (≤480px), elle se réduit à 1.
Exemple : cards_per_row="4"

card_alignment

Type : Chaîne de caractères
Par défaut : gauche
Options : left | center | right
Description : S'applique uniquement lorsque view="card". Aligne le texte et les éléments en ligne dans chaque carte.
Exemple : card_alignment="center"

font_size

Type : Entier
Par défaut : 14
Description : Définit la taille de police de base en pixels pour tout le texte du flux. Les éléments enfants dimensionnés en unités em s'adaptent proportionnellement.
Exemple : font_size="16"

Paramètres de filtre

campagne

Type : Chaîne de caractères (ID numérique)
Par défaut : (auto-détection)
Description : Filtre les dons pour une seule campagne par son ID de publication WordPress. Lorsqu'il est utilisé sur une page de campagne, la campagne est auto-détectée et ce paramètre peut être omis. Passez une chaîne vide pour toutes les campagnes.
Exemple : campaign="42"

trier_par

Type : Chaîne de caractères
Par défaut : date
Options : date | amount | first_name | last_name | campaign_name
Description : Le champ utilisé pour trier les résultats des dons.
Exemple : orderby="amount"

ordre

Type : Chaîne de caractères
Par défaut : DESC
Options : DESC | ASC
Description : Sens de tri. DESC affiche le plus récent/le plus élevé en premier ; ASC affiche le plus ancien/le plus bas en premier.
Exemple : order="ASC"

date_range

Type : Chaîne de caractères
Par défaut : tous_les_temps
Options : tous_les_temps | derniers_7_jours | derniers_30_jours | derniere_annee | personnalise
Description : Limite les résultats aux dons effectués dans une fenêtre temporelle. Utilisez personnalise avec date_from et date_to pour spécifier une plage exacte.
Exemple : date_range="derniers_30_jours"

date_from

Type : Chaîne (YYYY-MM-DD)
Par défaut : (vide)
Description : Date de début pour une plage de dates personnalisée. Utilisé uniquement lorsque date_range="personnalise".
Exemple : date_from="2025-01-01"

date_to

Type : Chaîne (YYYY-MM-DD)
Par défaut : (vide)
Description : Date de fin pour une plage de dates personnalisée. Utilisé uniquement lorsque date_range="personnalise".
Exemple : date_to="2025-12-31"

minimum_amount

Type : Flottant
Par défaut : 0
Description : Affiche uniquement les dons d'un montant égal ou supérieur. Utile pour mettre en évidence les contributions importantes. Définir à 0 pour inclure tous les montants.
Exemple : minimum_amount="25"

include_anonymous

Type : Booléen
Par défaut : 1
Description : Indique s'il faut inclure les dons marqués comme anonymes. Lorsque cette option est activée, les donateurs anonymes sont affichés avec un nom d'espace réservé (« Anonyme ») et un avatar générique.
Exemple : include_anonymous="0"

include_recurring

Type : Booléen
Par défaut : 1
Description : Indique s'il faut inclure les paiements de dons récurrents dans le flux.
Exemple : include_recurring="0"

groupby_donor

Type : Booléen
Par défaut : 0
Description : Lorsque cette option est activée, plusieurs dons du même donateur sont regroupés en une seule entrée affichant leur total cumulé. Une étiquette « Total » est affichée sur les entrées regroupées. Utile pour créer un registre des donateurs plutôt qu'un journal des transactions.
Exemple : groupby_donor="1"

donor_search

Type : Chaîne de caractères
Par défaut : (vide)
Description : Filtre les résultats pour un donateur spécifique par nom (correspondance partielle du prénom, du nom de famille ou du nom complet). Si une valeur numérique est fournie, elle est traitée comme un ID de donateur pour une correspondance exacte.
Exemple : donor_search="Jane" ou donor_search="42"

donation_ids

Type : Chaîne de caractères (entiers séparés par des virgules)
Par défaut : (vide)
Description : Affiche uniquement les identifiants de dons spécifiques listés. Ceci remplace tous les autres paramètres de filtre (campagne, période, montant minimum, etc.) – seuls les dons listés apparaissent.
Exemple : donation_ids="101,205,308"

Paramètres d'affichage

show_header

Type : Booléen
Par défaut : 1
Description : Affiche ou masque la ligne d'en-tête de colonne (DONATEUR, MONTANT, DATE DU DON, COMMENTAIRE) en mode liste. N'a aucun effet en mode carte.
Exemple : show_header="0"

show_avatar

Type : Booléen
Par défaut : 1
Description : Affiche ou masque l'avatar Gravatar/profil du donateur. Les donateurs anonymes affichent un avatar générique de silhouette.
Exemple : show_avatar="0"

showprénom

Type : Booléen
Par défaut : 1
Description : Affiche ou masque le prénom du donateur. Peut être utilisé indépendamment de show_last_name pour n'afficher qu'un prénom pour des raisons de confidentialité.
Exemple : show_first_name="0"

shownom

Type : Booléen
Par défaut : 1
Description : Affiche ou masque le nom de famille du donateur. À combiner avec show_first_name="0" pour masquer toutes les informations de nom.
Exemple : show_last_name="0"

show_amount

Type : Booléen
Par défaut : 1
Description : Affiche ou masque le montant du don. Formaté selon les paramètres de devise actifs du site.
Exemple : show_amount="0"

afficher_date

Type : Booléen
Par défaut : 1
Description : Affiche ou masque la date du don. Affichée sous forme de temps relatif (par exemple, « il y a 3 jours ») avec la date/heure complète affichée au survol sous forme d'info-bulle.
Exemple : afficher_date="0"

afficher_commentaire

Type : Booléen
Par défaut : 1
Description : Affiche ou masque les commentaires des donateurs. Lorsqu'un commentaire dépasse comment_words, il est tronqué avec un bouton « Lire la suite » (sans rechargement de page).
Exemple : afficher_commentaire="0"

nombre_mots_commentaire

Type : Entier
Par défaut : 20
Description : Nombre maximum de mots à afficher avant de tronquer un commentaire de donateur avec un lien « Lire la suite ». S'applique uniquement lorsque afficher_commentaire="1".
Exemple : nombre_mots_commentaire="30"

afficher_campagne

Type : Booléen
Par défaut : 0
Description : Affiche ou masque le nom de la campagne pour chaque don. Utile lors de l'affichage d'un flux sur l'ensemble du site couvrant plusieurs campagnes. La position est contrôlée par campagne_affichage.
Exemple : afficher_campagne="1"

campagne_affichage

Type : Chaîne de caractères
Par défaut : colonne
Options : colonne | en_ligne
Description : S'applique uniquement lorsque afficher_campagne="1" en mode liste. colonne ajoute une colonne Campagne dédiée au tableau. en_ligne affiche le nom de la campagne sous le nom du donateur en texte plus petit.
Exemple : campagne_affichage="en_ligne"

afficher_localisation

Type : Booléen
Par défaut : 0
Description : Affiche ou masque l'emplacement principal du donateur (ville, état et/ou pays) sous son nom. L'emplacement est extrait de l'adresse principale du donateur enregistrée. Utilisez afficher_ville, afficher_etat, et afficher_pays pour contrôler les composants individuels.
Exemple : afficher_localisation="1"

afficher_ville

Type : Booléen
Par défaut : 1
Description : Affiche ou masque la partie ville de l'emplacement du donateur. S'applique uniquement lorsque afficher_localisation="1".
Exemple : afficher_ville="0"

afficher_etat

Type : Booléen
Par défaut : 1
Description : Affiche ou masque la partie état/province de l'emplacement du donateur. S'applique uniquement lorsque afficher_localisation="1".
Exemple : afficher_etat="0"

afficher_pays

Type : Booléen
Par défaut : 1
Description : Affiche ou masque la partie pays de l'emplacement du donateur. S'applique uniquement lorsque afficher_localisation="1". Utile pour les organisations d'un seul pays où le pays est redondant.
Exemple : afficher_pays="0"

Paramètres de pagination

pagination

Type : Booléen
Défaut : 0 (désactivé)
Description : Active la pagination pilotée par AJAX. Lorsqu’elle est activée, utilisez pagination_type pour choisir entre des pages numérotées et un bouton Charger plus.
Exemple : pagination="1"

pagination_type

Type : Chaîne de caractères
Par défaut : pages
Options : pages | load_more
Description : S’applique uniquement lorsque pagination="1". pages affiche des liens de page numérotés avec Précédent/Suivant et un résumé « Affichage de X à Y sur Z dons ». load_more affiche un seul bouton qui ajoute le lot de résultats suivant sous la liste existante.
Exemple : pagination_type="load_more"

Paramètres de titre et de texte

titre

Type : Chaîne de caractères
Par défaut : (vide)
Description : Titre facultatif affiché au-dessus du flux. Rendu sous forme d’élément <h2> avec la classe charitable-donations-feed-title.
Exemple : title="Dons récents"

description

Type : Chaîne de caractères
Par défaut : (vide)
Description : Sous-titre facultatif ou texte d’introduction affiché sous le titre et au-dessus du flux.
Exemple : description="Merci à tous ceux qui ont contribué !"

css_class

Type : Chaîne de caractères
Par défaut : (vide)
Description : Une ou plusieurs classes CSS supplémentaires ajoutées au conteneur le plus externe <div>. Utilisez pour appliquer un style personnalisé de votre thème.
Exemple : css_class="my-feed sidebar-feed"

Paramètres de style

alt_rows

Type : Booléen
Défaut : 1 (activé)
Description : Active les couleurs d’arrière-plan alternées des lignes en mode liste. La couleur d’arrière-plan alternée est contrôlée par le paramètre color_bg_alt ou la variable CSS.
Exemple : alt_rows="0"

Paramètres de personnalisation des couleurs

Tous les paramètres de couleur acceptent n’importe quelle valeur de couleur CSS valide : hexadécimal (#3A81C1), rgb(), hsl(), ou couleurs nommées. Passez une chaîne vide pour utiliser la valeur par défaut.

color_primary

Type : Chaîne (couleur CSS)
Par défaut : #3A81C1
Description : Couleur principale/d’accentuation. Utilisée pour les arrière-plans des boutons de pagination, les liens de campagne et la couleur du lien « Lire la suite ».
Exemple : color_primary="#e05c1a"

color_amount

Type : Chaîne (couleur CSS)
Par défaut : #2c7a2c
Description : Couleur du texte du montant du don (vert par défaut pour indiquer une valeur positive).
Exemple : color_amount="#1a6e8e"

color_border

Type : Chaîne (couleur CSS)
Par défaut : #d9d9d9
Description : Couleur des séparateurs de lignes, des bordures de cartes et des bordures des boutons de pagination.
Exemple : color_border="#cccccc"

colorbgalt

Type : Chaîne (couleur CSS)
Par défaut : #f0f0f0
Description : Couleur d'arrière-plan des lignes alternées (vue liste) ou de l'arrière-plan du badge groupé.
Exemple : color_bg_alt="#f5f0e8"

colorbghover

Type : Chaîne (couleur CSS)
Par défaut : #f5f5f5
Description : Couleur d'arrière-plan appliquée lors du survol d'une ligne (vue liste) ou d'une carte (vue carte).
Exemple : color_bg_hover="#eaf4fb"

colortextheader

Type : Chaîne (couleur CSS)
Par défaut : #636364
Description : Couleur des étiquettes d'en-tête de colonne (DONATEUR, MONTANT, etc.) et de toutes les sous-étiquettes utilisant font-size: 11px.
Exemple : color_text_header="#444444"

colortextinfo

Type : Chaîne (couleur CSS)
Par défaut : #797b7c
Description : Couleur du texte secondaire – dates relatives, lieu du donateur, nom de la campagne en mode inline, et texte du commentaire.
Exemple : color_text_info="#888888"

Exemples

Basique – Tous les défauts

[charitable_donations_feed]

Affiche les 10 dons les plus récents de toutes les campagnes, vue liste, tous les champs visibles, pas de pagination.

Grille de cartes pour une page de campagne

[charitable_donations_feed view="card" cards_per_row="3" card_alignment="center" number="9"]

Mettre en avant les grands donateurs

[charitable_donations_feed minimum_amount="100" orderby="amount" order="DESC" number="5" title="Our Champions" description="These donors have gone above and beyond."]

Adapté aux anonymes avec seulement le prénom

[charitable_donations_feed show_last_name="0" include_anonymous="1" show_comment="0" number="15"]

Tableau des dons (Totaux regroupés)

[charitable_donations_feed groupby_donor="1" orderby="amount" number="20" show_date="0" show_comment="0" title="Our Donors"]

Regroupe tous les dons par personne en une seule entrée montrant leur total cumulé, trié du plus élevé au plus bas.

Charger plus de pagination, 30 derniers jours

[charitable_donations_feed pagination="1" pagination_type="load_more" number="10" date_range="last_30_days"]

Flux spécifique à la campagne avec localisation

[charitable_donations_feed campaign="88" show_location="1" show_city="1" show_state="1" show_country="0" show_campaign="0"]

Vitrine organisée de dons spécifiques

[charitable_donations_feed donation_ids="101,205,308,412" show_header="0" view="card" cards_per_row="4"]

Thème de couleur personnalisé

[charitable_donations_feed color_primary="#c0392b" color_amount="#c0392b" color_border="#f0c0bb" color_bg_alt="#fdf5f5" color_bg_hover="#fce8e8"]

Personnalisation

Remplacement de modèles

Le flux de dons utilise deux fichiers de modèle qui peuvent être remplacés à partir de votre thème actif :

Emplacements des modèles de plugin :charitable-pro/templates/donations-feed/donations-feed-list.php (vue liste) charitable-pro/templates/donations-feed/donations-feed-cards.php (vue carte)

Pour remplacer, copiez dans votre thème :votre-theme/charitable/donations-feed/donations-feed-list.php votre-theme/charitable/donations-feed/donations-feed-cards.php

Variables disponibles dans les modèles :

Variable	Type	Description
`$dons`	`tableau`	Tableau de tableaux de données de dons (voir ci-dessous)
`$nombre_total`	`entier`	Nombre total de dons correspondants (pour les calculs de pagination)
`$args`	`tableau`	Arguments de shortcode/bloc normalisés

Clés disponibles dans chaque tableau $don :

Clé	Description
`id_don`	ID de publication WordPress du don
`id_donateur`	ID du donateur Charitable
`nom`	Nom d'affichage (pré-formaté, respecte le paramètre anonyme)
`prenom_brut`	Prénom (brut, pour affichage conditionnel)
`nom_de_famille_brut`	Nom de famille (brut, pour affichage conditionnel)
`montant`	Montant du don (float)
`date`	Date du don en GMT (`Y-m-d H:i:s`)
`commentaire`	Commentaire du donateur (texte brut)
`avatar_html`	HTML complet `<img>` pour l'avatar du donateur
`est_anonyme`	Booléen – si le don est anonyme
`est_regroupe`	Booléen – si c'est une entrée de total groupé
`nom_campagne`	Titre de la campagne
`lien_campagne`	URL de la page de la campagne
`lieu`	Tableau avec les clés `ville`, `état`, `pays`

Personnalisation CSS

Le flux utilise des classes BEM en espace de noms. Classes clés :

Conteneur :css .charitable-donations-feed /* conteneur le plus externe (toutes les vues) */ .charitable-donations-feed-list /* modificateur de vue liste */ .charitable-donations-feed-cards /* modificateur de vue carte */ .charitable-donations-feed-alt-rows /* modificateur de lignes alternées (vue liste) */

Vue Liste :css .charitable-donations-feed-table /* l'élément <table> */ .charitable-donations-feed-col-donor /* colonne donateur th/td */ .charitable-donations-feed-col-amount /* colonne montant th/td */ .charitable-donations-feed-col-date /* colonne date th/td */ .charitable-donations-feed-col-campaign /* colonne campagne th/td */ .charitable-donations-feed-col-comment /* colonne commentaire th/td */ .charitable-donations-feed-row /* chaque <tr> */ .charitable-donations-feed-donor-info /* conteneur flex : avatar + nom */ .charitable-donations-feed-donor-name /* texte du nom du donateur */ .charitable-donations-feed-donor-location /* ligne ville/état/pays */

Vue Carte :css .charitable-donations-feed-cards-grid /* conteneur CSS grid */ .charitable-donations-feed-card /* carte individuelle */ .charitable-donations-feed-card-amount /* montant principal dans la carte */ .charitable-donations-feed-card-donor /* ligne du donateur dans la carte */ .charitable-donations-feed-card-date /* date dans la carte */ .charitable-donations-feed-card-campaign /* nom de la campagne dans la carte */ .charitable-donations-feed-card-comment /* bloc de commentaire dans la carte */

Exemple : ajouter un accent de bordure gauche aux cartes :css .charitable-donations-feed-card { border-left: 4px solid #3A81C1; }

Variables CSS

Tous les styles visuels par défaut sont contrôlés par des propriétés CSS personnalisées sur l'élément conteneur .charitable-donations-feed. Remplacez-les globalement ou limitez-les à une instance spécifique en utilisant son id unique.

Variable	Défaut	Contrôles
`--charitable-df-primary`	`#3A81C1`	Couleur d'accentuation (liens, boutons)
`--charitable-df-amount`	`#2c7a2c`	Texte du montant du don
`--charitable-df-border`	`#d9d9d9`	Séparateurs de ligne, bordures de carte
`--charitable-df-bg-alt`	`#f0f0f0`	Arrière-plan alternatif des lignes
`--charitable-df-bg-hover`	`#f5f5f5`	Arrière-plan au survol des lignes/cartes
`--charitable-df-text-header`	`#636364`	Libellés des en-têtes de colonne
`--charitable-df-text-info`	`#797b7c`	Texte secondaire/méta
`--charitable-df-font-size`	`14px`	Taille de police de base
`--charitable-df-cards-par-ligne`	`3`	Colonnes de la grille de cartes

Exemple de remplacement global :css .charitable-donations-feed { --charitable-df-primary: #c0392b; --charitable-df-amount: #c0392b; --charitable-df-border: #f0c0bb; }

Remplacement spécifique à l'instance (utilisez le champ CSS personnalisé du bloc ou un wrapper unique) : “`css

my-homepage-feed {

--charitable-df-font-size: 16px;
--charitable-df-bg-alt: transparent;

} “`

Filtres et Hooks WordPress

Le flux de dons expose neuf hooks de filtre pour les développeurs qui ont besoin de personnaliser la logique de requête, de modifier les données de don avant le rendu ou de modifier le HTML de sortie.

`charitable_donations_feed_query_args`

Filtre le tableau d'arguments normalisés immédiatement après l'analyse et la validation des attributs du shortcode/bloc. Utilisez ceci pour remplacer n'importe quel paramètre par programmation – par exemple, pour forcer une campagne ou un montant minimum sur toutes les instances du flux.

Paramètres :

Paramètre	Type	Description
`$args`	`tableau`	Le tableau complet des arguments normalisés

Exemple :

// Always force-enable groupby_donor for all feeds.
add_filter( 'charitable_donations_feed_query_args', function( $args ) {
    $args['groupby_donor'] = true;
    return $args;
} );

`charitable_donations_feed_where_clauses`

Filtre les clauses WHERE SQL avant l'exécution de la requête de base de données. Chaque élément du tableau est un fragment SQL complet (sûr, déjà préparé). Utilisez ceci pour ajouter des conditions personnalisées – par exemple, pour limiter les résultats à un segment de donateur spécifique.

Paramètres :

Paramètre	Type	Description
`$where`	`tableau`	Tableau de chaînes de clauses WHERE SQL
`$args`	`tableau`	Le tableau des arguments normalisés

Exemple :

// Exclude donations with a specific meta value.
add_filter( 'charitable_donations_feed_where_clauses', function( $where, $args ) {
    global $wpdb;
    $where[] = $wpdb->prepare(
        "d.donation_id NOT IN ( SELECT donation_id FROM {$wpdb->postmeta} WHERE meta_key = '_hide_from_feed' AND meta_value = '1' )"
    );
    return $where;
}, 10, 2 );

`charitable_donations_feed_donation_data`

Filtre le tableau de données pour un seul don immédiatement après sa construction à partir de la ligne de base de données. Utilisez ceci pour ajouter des champs personnalisés, modifier les valeurs d'affichage ou joindre des données externes à chaque entrée.

Paramètres :

Paramètre	Type	Description
`$data`	`tableau`	Le tableau des données de don (voir les variables de modèle ci-dessus)
`$row`	`objet`	L'objet de ligne de base de données brut

Exemple :

// Add a custom badge field based on donation amount.
add_filter( 'charitable_donations_feed_donation_data', function( $data, $row ) {
    $data['badge'] = $data['amount'] >= 500 ? 'Major Donor' : '';
    return $data;
}, 10, 2 );

`charitable_donations_feed_donations`

Filtre le tableau complet des données de dons après le traitement de toutes les lignes. Utilisez ceci pour réorganiser, dédupliquer ou tronquer l'ensemble de résultats final avant qu'il ne soit transmis au modèle.

Paramètres :

Paramètre	Type	Description
`$dons`	`tableau`	Tableau de tous les tableaux de données de dons pour cette page
`$args`	`tableau`	Le tableau des arguments normalisés

Exemple :

// Shuffle the donations for a randomized display.
add_filter( 'charitable_donations_feed_donations', function( $donations, $args ) {
    if ( ! empty( $args['randomize'] ) ) {
        shuffle( $donations );
    }
    return $donations;
}, 10, 2 );

`charitable_donations_feed_display_name`

Filtre la chaîne de nom d'affichage d'un donateur avant qu'elle ne soit placée dans le tableau des données de don. Utilisez ceci pour personnaliser l'apparence des noms – par exemple, pour utiliser des initiales, un nom d'utilisateur ou un format personnalisé.

Paramètres :

Paramètre	Type	Description
`$name`	`chaîne de caractères`	Le nom d'affichage formaté
`$donor_id`	`entier`	L'ID du donateur Charitable
`$donation_id`	`entier`	L'ID de publication du don WordPress
`$anonymous`	`bool`	Si le don est anonyme

Exemple :

// Show only first name + last initial.
add_filter( 'charitable_donations_feed_display_name', function( $name, $donor_id, $donation_id, $anonymous ) {
    if ( $anonymous ) {
        return $name;
    }
    $parts = explode( ' ', $name, 2 );
    if ( isset( $parts[1] ) ) {
        return $parts[0] . ' ' . substr( $parts[1], 0, 1 ) . '.';
    }
    return $name;
}, 10, 4 );

`charitable_donations_feed_avatar_html`

Filtre la chaîne HTML complète <img> pour l'avatar d'un donateur. Utilisez ceci pour échanger une image personnalisée, ajouter des classes CSS ou remplacer l'avatar par un autre élément.

Paramètres :

Paramètre	Type	Description
`$html`	`chaîne de caractères`	Le HTML complet de l'`<img>`
`$donor_id`	`entier`	L'ID du donateur Charitable
`$donation_id`	`entier`	L'ID de publication du don WordPress
`$size`	`entier`	Taille de l'avatar demandée en pixels

Exemple :

// Replace the avatar with a custom icon for VIP donors.
add_filter( 'charitable_donations_feed_avatar_html', function( $html, $donor_id, $donation_id, $size ) {
    if ( charitable_is_vip_donor( $donor_id ) ) {
        return '<img src="' . esc_url( get_stylesheet_directory_uri() . '/images/vip-badge.png' ) . '" width="' . $size . '" height="' . $size . '" class="charitable-donations-feed-avatar-img vip" alt="VIP Donor" />';
    }
    return $html;
}, 10, 4 );

`charitable_donations_feed_donor_location`

Filtre le tableau des données de localisation d'un donateur avant qu'il ne soit attaché à l'entrée de don. Utilisez ceci pour remplacer les valeurs de localisation, traduire les codes pays en noms, ou ajouter des valeurs de secours.

Paramètres :

Paramètre	Type	Description
`$location`	`tableau`	Tableau avec les clés `ville`, `état`, `pays`
`$donor_id`	`entier`	L'ID du donateur Charitable

Exemple :

// Convert country codes to full names using a lookup.
add_filter( 'charitable_donations_feed_donor_location', function( $location, $donor_id ) {
    $country_names = array( 'US' => 'United States', 'CA' => 'Canada', 'GB' => 'United Kingdom' );
    if ( isset( $country_names[ $location['country'] ] ) ) {
        $location['country'] = $country_names[ $location['country'] ];
    }
    return $location;
}, 10, 2 );

`charitable_donations_feed_args`

Filtre le tableau final des arguments juste avant l'exécution de la requête de base de données, après toute la normalisation et le traitement de compatibilité ascendante. C'est la dernière occasion de modifier les arguments avant qu'ils n'affectent la requête.

Paramètres :

Paramètre	Type	Description
`$args`	`tableau`	Le tableau d'arguments entièrement normalisé

Exemple :

// Programmatically restrict feeds on a specific page to the last 30 days.
add_filter( 'charitable_donations_feed_args', function( $args ) {
    if ( is_page( 'donate' ) && 'all_time' === $args['date_range'] ) {
        $args['date_range'] = 'last_30_days';
    }
    return $args;
} );

`charitable_donations_feed_css_variables`

Filtre la chaîne de variables CSS inline injectée dans l'attribut style du flux. Utilisez ceci pour ajouter des propriétés personnalisées CSS supplémentaires ou remplacer celles existantes par programmation.

Paramètres :

Paramètre	Type	Description
`$css_string`	`chaîne de caractères`	Les déclarations de variables CSS inline (par exemple, `--charitable-df-primary: #c00;`)
`$args`	`tableau`	Le tableau des arguments normalisés

Exemple :

// Automatically match the primary color to the active campaign's accent color.
add_filter( 'charitable_donations_feed_css_variables', function( $css_string, $args ) {
    if ( ! empty( $args['campaign'] ) ) {
        $accent = get_post_meta( $args['campaign'], '_campaign_accent_color', true );
        if ( $accent ) {
            $css_string .= ' --charitable-df-primary: ' . sanitize_hex_color( $accent ) . ';';
        }
    }
    return $css_string;
}, 10, 2 );

Dépannage

Le flux n'affiche aucune donation

Confirmez qu'au moins une donation avec le Statut : Terminé existe dans votre base de données.
Vérifiez que le paramètre campaign (s'il est défini) correspond à un identifiant de publication de campagne valide.
Si vous utilisez donation_ids, vérifiez que les identifiants sont des entiers séparés par des virgules sans espaces.
Si vous utilisez minimum_amount, vérifiez si des dons atteignent le seuil.
Si vous utilisez une date_range="custom" personnalisée, assurez-vous que date_from et date_to sont au format YYYY-MM-DD.

Les noms des donateurs sont coupés en mode liste

Ceci est généralement causé par une feuille de style de thème qui remplace la règle white-space: nowrap sur la colonne du donateur. Ajoutez ce qui suit à votre CSS de thème : .charitable-donations-feed-list .charitable-donations-feed-donor-info { width: max-content; }

La pagination ne fonctionne pas

Assurez-vous que pagination="on" (ou activez-la dans les paramètres du bloc).
Pour le bouton Charger plus, vérifiez que l'action charitable_donations_feed_ajax n'est pas bloquée par un plugin de sécurité ou un pare-feu.
Vérifiez la console de votre navigateur pour les erreurs JavaScript qui pourraient indiquer que l'objet JS charitable_donations_feed n'est pas défini sur la page.

La vue carte ne respecte pas cards_per_row

Ce paramètre est injecté en tant que propriété personnalisée CSS (--charitable-df-cards-per-row). Si un thème a une règle grid-template-columns ciblant .charitable-donations-feed-cards-grid, elle peut remplacer la variable. Inspectez avec les outils de développement du navigateur et ajoutez une règle plus spécifique si nécessaire.

La localisation est vide même si le donateur a une adresse

La fonctionnalité de localisation lit l'adresse principale du donateur à partir de charitable_donormeta. Si le donateur a complété une donation sans entrer de champs d'adresse, l'adresse sera vide. Les champs de localisation sont facultatifs dans le formulaire de don par défaut.

FAQ

Puis-je afficher le flux pour plusieurs campagnes spécifiques à la fois ? Pas directement – le paramètre campaign accepte un seul ID de campagne. Utilisez donation_ids pour sélectionner manuellement des dons de plusieurs campagnes, ou omettez complètement campaign pour afficher toutes les campagnes et utilisez show_campaign="1" pour afficher le nom de la campagne à côté de chaque entrée.

Le flux de dons affiche-t-il les dons en temps réel sans actualisation de la page ? Le flux n'est pas un flux WebSocket en direct – il reflète l'état de la base de données au chargement de la page (ou à la demande de pagination). Pour une expérience « quasi en temps réel », utilisez un court TTL de cache de page ou désactivez la mise en cache de page sur les pages avec le flux.

Puis-je utiliser le flux de dons dans un widget de barre latérale ? Oui. Utilisez le widget Shortcode (intégré à WordPress) ou tout widget prenant en charge les shortcodes. La vue carte à cards_per_row="1" fonctionne bien dans une barre latérale étroite.

La fonction groupby_donor fonctionne-t-elle avec le filtre de recherche de donateurs ? Oui. Lorsque groupby_donor est activé, la recherche de donateurs filtre toujours par nom/ID de donateur, mais le montant affiché est le total du donateur sur tous les dons correspondants.

Puis-je utiliser le shortcode dans un constructeur de page (Elementor, Divi, WPBakery) ? Oui. Charitable Pro inclut des intégrations natives pour Elementor et Divi. Pour WPBakery ou d'autres constructeurs, utilisez un élément/module de shortcode et collez le shortcode directement.

Les dons anonymes afficheront-ils des informations ? Lorsque include_anonymous="1" (par défaut), les dons anonymes apparaissent avec le nom d'espace réservé « Anonyme » et un avatar de silhouette générique. Tous les autres champs (montant, date, commentaire) s'affichent normalement. Définissez include_anonymous="0" pour les exclure complètement.

Ressources supplémentaires

Documentation du classement des donateurs – Fonctionnalité associée : affichage classé des donateurs avec des icônes de trophée.
Système de modèles Charitable – Comment remplacer les modèles de votre thème.
Personnalisation CSS de Charitable – Guide général pour styliser la sortie de Charitable.

Journal des modifications

Version	Modifications
1.8.13	Version initiale du shortcode et du bloc Gutenberg pour le flux de dons.

Documentation Charitable

Ressources populaires

Table des matières

Fonctionnalités clés

Pourquoi utiliser un flux de dons ?

Cas d'utilisation

Voyez-le en action

Démarrage

Exigences

Activation

Méthodes d'utilisation

Raccourci

Bloc Gutenberg WordPress

Référence complète des paramètres

Paramètres principaux

vue

nombre

cartes par ligne

card_alignment

font_size

Paramètres de filtre

campagne

trier_par

ordre

date_range

date_from

date_to

minimum_amount

include_anonymous

include_recurring

groupby_donor

donor_search

donation_ids

Paramètres d'affichage

show_header

show_avatar

showprénom

shownom

show_amount

afficher_date

afficher_commentaire

nombre_mots_commentaire

afficher_campagne

campagne_affichage

afficher_localisation

afficher_ville

afficher_etat

afficher_pays

Paramètres de pagination

pagination

pagination_type

Paramètres de titre et de texte

titre

description

css_class

Paramètres de style

alt_rows

Paramètres de personnalisation des couleurs

color_primary

color_amount

color_border

colorbgalt

colorbghover

colortextheader

colortextinfo

Exemples

Basique – Tous les défauts

Grille de cartes pour une page de campagne

Mettre en avant les grands donateurs

Adapté aux anonymes avec seulement le prénom

Tableau des dons (Totaux regroupés)

Charger plus de pagination, 30 derniers jours

Flux spécifique à la campagne avec localisation

Vitrine organisée de dons spécifiques

Thème de couleur personnalisé

Personnalisation

Remplacement de modèles

Personnalisation CSS

Variables CSS

`charitable_donations_feed_query_args`

`charitable_donations_feed_where_clauses`

`charitable_donations_feed_donation_data`

`charitable_donations_feed_donations`

`charitable_donations_feed_display_name`

`charitable_donations_feed_avatar_html`

`charitable_donations_feed_donor_location`

`charitable_donations_feed_args`

`charitable_donations_feed_css_variables`