Souhaitez-vous qu'un champ personnalisé de votre formulaire de don apparaisse sur le reçu PDF ? Lorsque vous ajoutez un champ personnalisé à un ancien formulaire ou que vous en créez un dans le constructeur visuel de campagnes, Charitable enregistre la réponse du donateur avec le don – mais le modèle de reçu PDF ne l'imprime pas automatiquement. Vous devrez indiquer au reçu où se trouve la valeur et comment l'afficher.

Ce guide vous guidera à travers les étapes pour ajouter un champ de don personnalisé à votre reçu PDF, que le champ provienne d'un ancien formulaire ou du constructeur visuel de formulaires.

Remarque : Cette section suppose que vous utilisez Charitable Pro 1.8.13+ et implique une petite quantité de PHP. Si vous n'êtes pas à l'aise avec la modification de code, collez l'extrait dans un outil comme WPCode afin de ne pas avoir à toucher directement aux fichiers de thème, ou confiez-le à votre développeur.

Comment les champs personnalisés sont-ils stockés ?

Avant de pouvoir afficher un champ sur le reçu, vous avez besoin de deux choses : où sa valeur est stockée et par quelle clé la rechercher. Charitable enregistre les champs personnalisés des anciens formulaires et des formulaires visuels comme métadonnées de publication de don, mais la clé de métadonnées ressemble différemment selon le formulaire qui l'a créé.

Pour les champs personnalisés d'anciens formulaires, la clé de métadonnées est celle qui a été enregistrée avec le champ. Si vous avez enregistré un champ avec la clé t_shirt_size en utilisant l'API des champs de don Donation Fields API, la valeur est stockée sous cette clé exacte.

Pour les champs personnalisés de formulaires visuels, la clé utilise le format field_X, où X est l'ID numérique que le constructeur de campagnes a attribué au champ. Les champs masqués font exception – ceux-ci utilisent le nom que vous avez tapé dans le paramètre Nom du champ.

Trouver la clé de métadonnées de votre champ

Le moyen le plus simple de confirmer quelle clé de métadonnées un champ utilise est de regarder un don réel qui incluait le champ.

Pour un ancien formulaire, la clé de métadonnées est la clé de tableau que vous avez utilisée lors de l'enregistrement du champ avec le filtre charitable_default_donation_fields. Si vous n'avez pas écrit le snippet vous-même, vous pouvez rechercher sur votre site (ou demander à votre développeur) ce filtre pour confirmer la clé.

Pour un formulaire visuel, allez dans Charitable » Dons, ouvrez un don de test qui a soumis le champ personnalisé, et recherchez dans les données enregistrées du don des entrées comme field_3 ou field_5. Le numéro est l'ID du champ dans le constructeur. Si vous préférez voir toutes les clés de métadonnées en une seule fois, vous pouvez ajouter ce snippet temporaire à n'importe quelle page d'administration :

echo '<pre>';
print_r( get_post_meta( 123 ) ); // Replace 123 with your test donation ID.
echo '</pre>';

Remarque : Une fois que vous avez noté les clés dont vous avez besoin, supprimez le snippet – laisser des appels print_r() dans la sortie de production est désordonné et peut fuiter des données de donateurs.

Ajout d'un champ à l'aide d'un hook (recommandé)

Charitable déclenche une action appelée charitable_pdf_receipt_after_donor_details juste après le bloc des détails du donateur sur chaque reçu PDF. S'accrocher à cette action est le moyen le plus simple d'ajouter un champ personnalisé, car vous n’avez pas à remplacer de fichiers de modèle – vos modifications survivent aux mises à jour du plugin sans travail supplémentaire.

Pour activer l'extrait, collez-le dans le fichier functions.php de votre thème enfant ou dans un plugin d'extraits de code :

add_action( 'charitable_pdf_receipt_after_donor_details', function( $donor, $donation ) {

    // Replace 't_shirt_size' with your field's meta key.
    // For a visual form custom field, this will look like 'field_3'.
    $value = get_post_meta( $donation->ID, 't_shirt_size', true );

    if ( empty( $value ) ) {
        return;
    }

    printf(
        '<p style="margin-top: 10px; margin-bottom: 0;"><strong>%s:</strong> %s</p>',
        esc_html__( 'T-Shirt Size', 'charitable-pro' ),
        esc_html( $value )
    );

}, 10, 2 );

L'exemple imprime le champ sous le nom, l'adresse et l'e-mail du donateur. Lors de l'adaptation, remplacez la clé méta, l'étiquette visible et le balisage pour correspondre au champ que vous ajoutez.

Remarque : Si votre valeur contient du HTML – par exemple, la sortie d'un champ de texte long – utilisez wp_kses_post() au lieu de esc_html() pour que les balises de formatage de base survivent.

Ajouter un champ en remplaçant le modèle

Si vous avez besoin de placer le champ ailleurs qu'après les détails du donateur – par exemple, dans le tableau des dons ou dans le pied de page – vous pouvez remplacer le modèle de reçu PDF.

Les modèles PDF de Charitable peuvent être remplacés par le thème. Pour personnaliser la mise en page PDF principale, copiez ce fichier :

wp-content/plugins/charitable-pro/templates/pro/pdf-receipts/pdf.php

Dans votre thème actif à ce chemin :

wp-content/themes/your-theme/charitable-pro/pro/pdf-receipts/pdf.php

Une fois votre copie en place, Charitable la chargera à la place de la version du plugin. Le même schéma de chemin fonctionne pour les deux modèles partiels que pdf.php appelle :

• Détails du donateur : templates/pro/pdf-receipts/donation-receipt/donor-details.php
• Détails du don : templates/pro/pdf-receipts/donation-receipt/details.php

À l'intérieur de tout modèle copié, la variable $donation est l'objet complet Charitable_Donation. Pour récupérer la valeur d'un champ personnalisé, utilisez le même appel get_post_meta() de la méthode précédente, puis ajoutez le balisage où vous souhaitez que la valeur apparaisse :

<?php
$value = get_post_meta( $donation->ID, 'field_3', true );
if ( ! empty( $value ) ) :
    ?>
    <p><strong><?php esc_html_e( 'Gift Aid Eligible', 'charitable-pro' ); ?>:</strong> <?php echo esc_html( $value ); ?></p>
    <?php
endif;
?>

Remarque : Les remplacements de modèles doivent être revus à chaque mise à jour de Charitable Pro. Si la version du plugin du modèle intègre de nouvelles fonctionnalités ou des corrections de bugs, votre remplacement ne les verra pas automatiquement. La méthode du crochet ci-dessus évite cela entièrement, utilisez donc un remplacement de modèle uniquement lorsque vous avez besoin de contrôler le placement.

Aperçu de vos modifications

Une fois votre extrait ou remplacement de modèle enregistré, générez un vrai PDF pour confirmer que le champ apparaît comme prévu. Depuis l'écran Charitable » Dons, choisissez un don qui incluait le champ personnalisé, puis cliquez sur l'icône PDF à côté pour télécharger le reçu. Si le champ n'apparaît pas, parcourez ces vérifications une par une :

• Confirmez que la clé méta correspond exactement – field_3 et field_03 ne sont pas la même chose.
• Vérifiez que le don que vous testez a bien soumis une valeur pour le champ. Les valeurs vides ne seront pas imprimées.
• Essayez un autre don de test pour exclure qu'une entrée soit vide.

Note : Les valeurs des champs qui semblent vides sur l'écran d'administration des dons seront également vides sur le PDF. Le reçu ne peut pas afficher de données que le don n'a jamais collectées.