Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Soumettre une campagne est le formulaire que vos ambassadeurs remplissent pour créer une collecte de fonds. Il se trouve derrière le shortcode [charitable_submit_campaign] et les guide à travers trois étapes :

• Choisir le type de destinataire (fais-je une collecte de fonds en tant qu'individu ? une équipe ? un membre d'équipe ?)
• Choisir la cause parente pour laquelle ils font une collecte de fonds
• Remplir les détails de la campagne (titre, histoire, objectif, image)

La version 3.0 introduit une étape 1 avec grille de cartes qui remplace le flux hérité basé sur la sélection. Même modèle de données, expérience utilisateur beaucoup plus conviviale – le destinataire devient une sélection de carte tactile, la campagne parente devient un sélecteur riche avec logos et barres de progression au lieu d'une longue liste déroulante.

Quand l'utiliser

• Configuration – L'assistant de configuration crée automatiquement une page /submit-campaign/ avec le shortcode. Visitez-la une fois pour confirmer.
• Lier directement les ambassadeurs à une cause spécifique – partagez ?cap_recipient=individual&cap_campaign=42 et le formulaire présélectionne ces choix.
• Thème – copiez le modèle dans votre thème pour apporter des modifications de mise en page à l'échelle du site.

Trouver la page

/submit-campaign/ (ou le slug que vous avez utilisé). La page affiche le formulaire pour les ambassadeurs connectés et invite à la connexion ou redirige automatiquement vers la connexion (configurable sous Général » Exiger un compte avant la soumission).

Si vous avez également besoin de trouver les paramètres qui régissent le formulaire :

Admin WordPress > Charitable > Ambassadeurs > Général

Le sous-onglet Général contient les Types de campagne disponibles, la Sélection par défaut, le Slug de l'URL de la collecte de fonds, Exiger un compte avant la soumission, Exiger la vérification par e-mail, Approuver automatiquement les campagnes, Longueur minimale/maximale de la campagne et la méthode de paiement.

Comment utiliser la soumission de campagne chez les ambassadeurs

Étape 1 – Choisir votre destinataire

La première étape demande : pour qui cette collecte de fonds est-elle ? La grille de cartes affiche les types de destinataires que vous avez activés dans Général » Types de campagne disponibles :

Carte	Choix si
Individuel	L'ambassadeur fait une collecte de fonds seul. Le cas le plus courant.
Équipe	L'ambassadeur crée une nouvelle équipe à laquelle d'autres ambassadeurs se joindront.
Membre d'équipe	L'ambassadeur rejoint une équipe existante en tant que membre.

La grille de cartes est limitée par la Version de l'interface utilisateur étant enhanced ou visual. Les sites toujours sur l'héritage voient l'étape originale basée sur la sélection. Le paramètre du site Sélection par défaut contrôle quelle carte est présélectionnée au chargement du formulaire – le premier type activé, un type spécifique, ou « Exiger que l'utilisateur choisisse » (aucune présélection, bouton Continuer désactivé).

Lorsque seule une carte est activée sur l'ensemble du site, le formulaire avance automatiquement après l'étape 1 – aucun intérêt à poser la question.

Étape 2 – Choisir une campagne parente

Si votre site comporte plusieurs campagnes mères compatibles peer-to-peer, l'étape 2 est le sélecteur de campagne mère :

Le sélecteur affiche une carte pour chaque campagne mère disponible avec la miniature, le titre, le montant collecté actuel par rapport à l'objectif, et un bouton "Choisir celle-ci". Il y a un champ de recherche au-dessus de la grille pour les sites avec de nombreuses campagnes mères.

Le sélecteur est piloté par AJAX – il interroge un point de terminaison qui ne renvoie que les campagnes pour lesquelles l'ambassadeur actuel est éligible à la collecte de fonds. C'est important : il exclut les campagnes inactives, les campagnes expirées et toute campagne restreinte par charitable_ambassadors_user_can_invite ou des mécanismes similaires.

Continuer est désactivé jusqu'à ce qu'une campagne mère soit sélectionnée.

Si le destinataire à l'étape 1 était Membre d'équipe, cette étape est remplacée par un sélecteur d'équipe qui affiche les équipes existantes sous forme de cartes compactes "Rejoindre l'équipe".

Étape 3 – Remplir les détails de la campagne

L'étape 3 est le long formulaire : titre, histoire, objectif, date de fin, montants de don suggérés, image mise en avant. Cette étape est ce que le formulaire standard de soumission de campagne de Charitable Pro génère. Il respecte tous les paramètres de champ configurés dans les paramètres généraux de Charitable.

Soumettre, et :

• Un nouvel article de campagne est créé en tant que brouillon (ou en attente si l'approbation automatique des campagnes est désactivée).
• L'action charitable_campaign_submission_save est déclenchée, à laquelle le gestionnaire d'attribution des invitations réagit.
• Si l'approbation automatique est activée, la campagne de collecte de fonds est publiée immédiatement.
• Si l'approbation automatique est désactivée, la campagne de collecte de fonds arrive en Modération pour que votre équipe l'examine.

Lien profond avec cap_recipient et cap_campaign

Vous pouvez pré-remplir les étapes 1 et 2 en ajoutant des arguments de requête à l'URL de soumission :

/submit-campaign/?cap_recipient=individual&cap_campaign=42

Argument	Ce qu'il présélectionne
cap_destinataire	individual / team / team-member – le type de destinataire.
cap_campagne	Un ID de campagne mère. S'il est valide, le sélecteur est ignoré et la campagne mère est verrouillée.

Les noms des arguments de requête sont filtrables via charitable_ambassadors_submit_form_query_arg_names si vous avez besoin d'utiliser des noms différents (pour la compatibilité avec les URL existantes).

La fenêtre contextuelle "Recruter pour cette campagne" sur Mes campagnes génère des URL de cette forme exacte, donc lorsqu'un recrue clique sur un lien d'invitation, le formulaire commence pré-rempli avec la bonne campagne mère.

Le shortcode

[charitable_submit_campaign]

Attribut optionnel :

[charitable_submit_campaign parent_id="42"]

Lorsque parent_id est défini, le shortcode verrouille la campagne mère lors du rendu (identique au passage de cap_campaign=42 dans l'URL).

Fichiers de modèle

Chemin	Utilisé quand
templates/shortcodes/submit-campaign.php	Version de l'interface utilisateur héritée.
templates/shortcodes/submit-campaign-enhanced.php	Versions de l'interface utilisateur améliorée + visuelle, lorsque le chemin de la grille de cartes est actif.
templates/shortcodes/submit-campaign/<partial>.php	Partiels par étape référencés par le shell amélioré.

Chemin de remplacement du thème : your-theme/charitable-pro/charitable-ambassadors/submit-campaign-enhanced.php (et les partiels par étape).

Éligibilité et accès

Paramètre	Défaut	Effet
Exiger un compte avant la soumission	Activé	Les ambassadeurs doivent être connectés. Les visiteurs déconnectés voient une invite de connexion avec une redirection vers la page de soumission.
Exiger la vérification par e-mail	Activé	Les ambassadeurs qui n'ont pas vérifié leur e-mail voient une invite de vérification au lieu du formulaire.
Approbation automatique des campagnes	Désactivé	Si vos soumissions sont plus ouvertes (« quiconque peut soumettre, nous nous en occuperons plus tard »), désactivez les deux indicateurs d'exigence. Si vous êtes plus strict (« seuls les comptes vérifiés peuvent soumettre »), activez les deux.

Si votre site est plus ouvert (« quiconque peut soumettre, nous nous en occuperons plus tard »), désactivez les deux indicateurs d'exigence. Si vous êtes plus strict (« seuls les comptes vérifiés peuvent soumettre »), activez les deux.

Plafond par destinataire

Vous pouvez limiter le nombre de collectes de fonds qu'un ambassadeur unique peut avoir à la fois via le filtre charitable_ambassadors_user_max_fundraisers. Lorsque la limite est dépassée, le bouton de soumission de l'étape 3 affiche un avis convivial « vous avez atteint votre limite de collecte de fonds » au lieu de soumettre.

Conseils

• Utilisez des URL avec des liens profonds dans vos e-mails d'invitation. Ne faites pas chercher aux ambassadeurs dans un sélecteur parent – si vous savez déjà pour quelle cause ils recrutent, passez cap_campaign=ID dans le lien.
• La sélection par défaut est importante. « Premier type activé » est accueillant ; « Exiger que l'utilisateur choisisse » est délibéré. Choisissez pour correspondre à la personnalité de votre programme.
• Approbation automatique pour les équipes de confiance, manuelle pour le public. Un gala pour vos donateurs existants ? Approbation automatique. Un p2p public ? Modération manuelle.
• Lisez les données de votre formulaire via le profil du répertoire. Lorsque vous avez besoin de savoir ce qu'un ambassadeur a rempli, l'onglet Données du formulaire sur son profil montre tout sans que vous ayez à vous connecter en tant que lui.

---

Référence du développeur

Le reste de cette page est destiné aux développeurs qui personnalisent le formulaire de soumission.

Raccourci

[charitable_submit_campaign]
[charitable_submit_campaign parent_id="42"]

Classe : Charitable_Ambassadors_Submit_Campaign_Shortcode. Le shortcode délègue à une instance de formulaire Charitable_Ambassadors_Campaign_Form et à son processeur.

Filtres

Filtre	Défaut	Objectif
charitable_submit_campaign_shortcode	HTML rendu	Filtrez la sortie complète du shortcode.
charitable_ambassadors_use_card_submit_form	calculé	Force le chemin de la grille de cartes activé/désactivé. Renvoie true lorsque la version de l'interface utilisateur est améliorée/visuelle et non héritée.
charitable_ambassadors_submit_form_query_arg_names	[ 'destinataire'=>'cap_destinataire', 'campagne'=>'cap_campagne' ]	Renommez les arguments de requête utilisés pour le deep linking.
charitable_ambassadors_step1_expected_total	calculé	Remplacez le nombre total d’étapes affiché dans la pilule « Étape 1 sur N » (la fonction get_pages() du formulaire ne peut pas voir les pages conditionnelles enregistrées en aval).
charitable_ambassadors_submit_form_recipient_card_help_url	''	URL d’un lien « En savoir plus » facultatif dans le texte d’aide de la carte du destinataire.
charitable_ambassadors_user_max_fundraisers	illimité	Nombre maximum de collectes de fonds publish + pending qu'un seul ambassadeur peut posséder.
charitable_campaign_submission_user_fields	calculé	Champs affichés dans la section des champs utilisateur de l'étape 3. Partagé avec le formulaire Ajouter un ambassadeur du Répertoire.

Actions

Action	Args	Se déclenche lorsque
charitable_ambassadors_before_submit_form_step1	–	Juste avant que le conteneur de l'étape 1 ne soit rendu.
charitable_ambassadors_after_submit_form_step1	–	Juste après l'étape 1.
charitable_submit_campaign_shortcode_hidden	$form_args	État déconnecté / sans permission rendu à la place du formulaire.
charitable_campaign_submission_save	$data, $campaign_id, $user_id, $form	Déclenché par Pro après que le formulaire a créé/mis à jour avec succès une campagne. Le gestionnaire d'attribution des invitations écoute ceci.

Points de terminaison AJAX

Action	Objectif
charitable_ambassadors_submit_picker_query	L'autocomplétion du sélecteur de campagne parente. Action nonce charitable_ambassadors_submit_picker, pas de contrôle de capacité (doit être connecté).

Aide à la détection d'URL

charitable_ambassadors_get_submit_form_query_args() // ['recipient' => 'individual'|'team'|..., 'campaign' => 0|int]

Utilisez ceci pour inspecter l'état du lien profond actif à partir de votre propre interface utilisateur personnalisée.

Vérifications des capacités

Le formulaire utilise Charitable_Ambassadors_Campaign_Form::current_user_can_edit_campaign() pour décider s'il faut rendre le formulaire. Renvoie false pour :

• Utilisateurs non connectés.
• Utilisateurs dont les comptes nécessitent une vérification par e-mail et qui ne l'ont pas effectuée.
• Utilisateurs sans la capacité de modifier les articles lors de la modification d'une campagne existante.

Partiels par étape

templates/shortcodes/submit-campaign/recipient-cards.php   # Step 1 cards
templates/shortcodes/submit-campaign/parent-picker.php     # Step 2 picker
templates/shortcodes/submit-campaign/team-picker.php       # Step 2 team variant
templates/shortcodes/submit-campaign/campaign-details.php  # Step 3 wrap

Chacun peut être remplacé par le thème via le même chemin your-theme/charitable-pro/charitable-ambassadors/<partial>.php.

Exemples de personnalisation

Forcer le formulaire de soumission hérité pour tous les utilisateurs (par exemple, lors d'un débogage de régression) :

add_filter( 'charitable_ambassadors_use_card_submit_form', '__return_false' );

Limiter chaque ambassadeur à une seule collecte de fonds simultanée :

add_filter( 'charitable_ambassadors_user_max_fundraisers', function () {
    return 1;
} );

Ajouter une bannière « Bienvenue de retour » au-dessus de l'étape 1 pour les ambassadeurs de retour :

add_action( 'charitable_ambassadors_before_submit_form_step1', function () {
    $user = wp_get_current_user();
    if ( $user && get_user_meta( $user->ID, '_charitable_ambassadors_submitted_before', true ) ) {
        echo '<div class="notice notice-info"><p>Welcome back, ' . esc_html( $user->display_name ) . '!</p></div>';
    }
} );

Renommer les arguments de requête (par exemple, pour la compatibilité descendante avec une campagne existante) :

add_filter( 'charitable_ambassadors_submit_form_query_arg_names', function () {
    return [ 'recipient' => 'team_type', 'campaign' => 'parent' ];
} );

Tamponner la collecte de fonds soumise avec l'URL de référence lors de la sauvegarde :

add_action( 'charitable_campaign_submission_save', function ( $data, $campaign_id, $user_id, $form ) {
    $ref = wp_get_referer();
    if ( $ref ) {
        update_post_meta( $campaign_id, '_referer_at_submit', esc_url_raw( $ref ) );
    }
}, 10, 4 );

Connexes

• Mes campagnes – où les ambassadeurs atterrissent après avoir soumis.
• Modération – où les soumissions vont pour examen.
• Invitations – Attribution – comment les clics sur les liens de parrainage sont liés aux soumissions.
• Assistant de configuration – l’assistant crée la page de soumission pour vous.
• Hooks & filtres dans Ambassadors – référence complète.

---