Documentation Charitable

Apprenez à tirer le meilleur parti de Charitable grâce à des instructions claires, étape par étape.

Champ_Don_Caritatif

La classe Champ_Don_Caritatif vous permet de créer de nouveaux champs de don ou de modifier ceux qui existent déjà.

Table des matières

Utilisation

Créer un nouveau champ de don

Si vous souhaitez ajouter un nouveau champ de don, vous devrez d'abord créer une nouvelle instance de Champ_Don_Caritatif, puis l'enregistrer dans le registre des champs de don.

add_action( 'init', function() {

    /* Create the Donation Field instance. */
    $field = new Charitable_Donation_Field(
        'my_custom_field',
        array(
            'label'          => __( 'My Custom Field' ),
            'data_type'      => 'meta', 
            'value_callback' => false,
            'donation_form'  => array(
                'type'       => 'text',
                'required'   => false,
                'show_after' => 'phone',
            ), 
            'admin_form'     => true,
            'show_in_meta'   => true,
            'show_in_export' => true,
            'email_tag'      => array(
                'description' => __( 'The custom field value' ),
            ),
        )
    );

    /* Register it. */
    charitable()->donation_fields()->register_field( $field );
} );

Obtenir un champ de don existant

Si vous souhaitez modifier ou changer un champ de don existant, la meilleure façon de procéder est d'obtenir l'objet du champ de don enregistré.

Vous pouvez ensuite utiliser set() ou le setter magique pour mettre à jour la définition du champ, ou utiliser le getter magique pour obtenir des informations sur le champ.

/* Get the Donation Fields Registry. */
$fields = charitable()->donation_fields();

/* Get the Phone field. */
$field = $fields->get_field( 'phone' );

/* Change the label (magic setter). */
$field->label = 'Mobile No.';

/* Change the field to be required. */
$field->set( 'donation_form', 'required', true );

/* Print out the field's label (magic getter). */
echo $field->label;

Propriétés

champ (string)

La clé ou l'identifiant du champ. Chaque champ doit avoir une clé unique.

label (chaîne de caractères)

L'étiquette du champ. C'est une description du champ. C'est ce qui sera utilisé dans le formulaire de don (sauf si vous le remplacez spécifiquement dans l'argument donation_form), dans la zone des détails des dons de l'administrateur et dans l'exportation des dons comme en-tête de colonne.

data_type (chaîne de caractères)

Le type de données que ce champ représente. Il existe deux options principales, avec une troisième utilisée principalement à des fins internes de Charitable :

  • user : Il s'agit d'informations spécifiques au donateur, et qui resteront généralement vraies pour le donateur lors des dons ultérieurs. Des exemples incluent son nom, son numéro de téléphone, etc.
  • meta : Il s'agit d'informations spécifiques au don. Un exemple serait le passerelle de paiement utilisée pour le don, ou si le donateur souhaite que ce don soit fait anonymement.
  • core : Ceci est principalement utilisé à des fins internes et ne devrait pas être utilisé dans la plupart des cas. Si vous l'utilisez, vous devrez vous assurer d'écrire du code supplémentaire pour stocker la valeur du champ, ainsi que pour la récupérer de la base de données.

value_callback (false|callable)

Comment la valeur du champ sera récupérée. Si vous omettez ceci ou le définissez sur false, le rappel par défaut sera utilisé en fonction du type de données du champ :

  • Pour un champ meta, le rappel de valeur par défaut est charitable_get_donor_meta_value.
  • Pour un champ user, le rappel de valeur par défaut est charitable_get_donation_meta_value.

Vous pouvez spécifier votre propre rappel de valeur en passant le nom de votre propre fonction, un tableau représentant une méthode d'objet [$class_name, $method_name], ou une fonction anonyme.

donation_form (false|array)

Comment/si le champ sera inclus dans le formulaire de don. Si ceci est omis ou défini sur false, le champ ne sera pas inclus du tout dans le formulaire de don. Lors du passage d'un tableau, les arguments suivants sont disponibles :

  • label (string)
    L'étiquette affichée dans le formulaire de don. Si ceci est omis, la propriété label du champ sera utilisée.
  • type (string)
    Le type de champ. Les options incluent :
    • texte
    • email
    • mot de passe
    • date
    • sélecteur de date
    • case à cocher
    • cases à cocher multiples
    • sélectionner
    • radio
    • fichier
    • groupe de champs
    • éditeur (utilise l'éditeur WordPress classique)
    • zone de texte
    • nombre
    • image
    • url
    • caché
  • requis (booléen)
    Indique si ce champ est obligatoire.
  • options (tableau)
    Fournit un ensemble d'options. Ceci est requis lorsque type est l'un de sélectionner, radio ou cases à cocher multiples. Celles-ci doivent être fournies dans un tableau simple valeur => libellé, où le libellé est ce que les gens voient lorsqu'ils sélectionnent une option, et la valeur est ce qui est stocké dans la base de données.
  • défaut (mixte)
    La valeur par défaut pour ce champ.
  • placeholder (chaîne)
    Un texte d'aide affiché dans le champ lorsqu'il est vide.
  • min (int)
    Définit le nombre minimum autorisé. Applicable uniquement si type est nombre.
  • max (int)
    Définit le nombre maximum autorisé. Applicable uniquement si type est nombre.
  • attrs (tableau)
    Un tableau d'attributs arbitraires à ajouter au champ de saisie.
  • section (chaîne)
    La section du formulaire de don dans laquelle ce champ doit apparaître. Il existe deux sections par défaut : utilisateur et méta. Si ce n'est pas défini, la section sera basée sur le type de données du champ.
  • show_before (chaîne)
    Définit où le champ doit être ajouté dans le formulaire de don en spécifiant le champ avant lequel il doit apparaître.
  • show_after (chaîne)
    Définit où le champ doit être ajouté dans le formulaire de don en spécifiant le champ après lequel il doit apparaître.
  • priority (int)
    Définit la position du champ dans le formulaire. Ceci est utilisé sauf si show_after ou show_before sont définis pour le champ. Si priority, show_after et show_before ne sont pas définis, le champ sera affiché après le champ de formulaire enregistré le plus récemment.
  • value_callback (false|callable)
    Une fonction de rappel pour récupérer la valeur du champ pour un don. Ceci remplacera le paramètre value_callback pour le champ.

admin_form (bool|array)

Définit si le champ doit être affiché dans le formulaire de don administrateur.

  • Si cette valeur est définie sur false, le champ ne sera pas affiché dans le formulaire de don administrateur (pas même en tant qu’entrée cachée).
  • Si cette valeur est définie sur true, le champ du formulaire héritera des arguments de donation_form (s’il est fourni) ou utilisera les arguments par défaut.
  • Alternativement, vous pouvez passer un tableau de valeurs pour affiner la façon dont ce champ est affiché dans le formulaire administrateur (tous les mêmes arguments sont acceptés que pour donation_form ci-dessus).

show_in_meta (bool)

Indique s’il faut inclure ce champ dans la section « Détails du don » d’une page d’administration des détails de don unique.

show_in_export (bool)

Indique s’il faut inclure ce champ dans l’exportation des dons disponible dans Charitable > Dons.

email_tag (bool|array)

Indique s’il faut créer une balise d’e-mail pour ce champ.

  • Si cette valeur est définie sur false, aucune balise d’e-mail ne sera créée.
  • Si cette valeur est définie sur true, une balise d’e-mail sera créée, en utilisant l’étiquette du champ comme description. Aucune valeur d’aperçu ne sera définie.
  • Alternativement, passez un tableau pour un contrôle plus fin sur les détails de la balise d’e-mail :
    • description (string)
      La description affichée pour la balise d’e-mail. Si aucune description n’est définie, l’étiquette du champ sera utilisée.
    • tag (string)
      La balise d’e-mail. Si elle n’est pas fournie, la clé du champ sera utilisée.
    • preview (mixed)
      Une valeur à utiliser dans les aperçus d’e-mail pour ce champ.

Méthodes

require()

Ajouté dans la version 1.5.0

Créer une nouvelle instance de champ de don.

Arguments

  • $field (chaîne de caractères)

    La clé unique du champ.

  • $args (tableau)

    Un tableau contenant toutes les propriétés présentées ci-dessus, à l’exception de $field.

Utilisation

$field = new Charitable_Donation_Field(
    'my_custom_field',
    array(
        'label'          => __( 'My Custom Field' ),
        'data_type'      => 'meta', 
        'value_callback' => false,
        'donation_form'  => array(
            'type'       => 'text',
            'required'   => false,
            'show_after' => 'phone',
        ), 
        'admin_form'     => true,
        'show_in_meta'   => true,
        'show_in_export' => true,
        'email_tag'      => array(
            'description' => __( 'The custom field value' ),
        ),
    )
);

require()

Ajouté dans la version 1.6.0

Modifier un argument de champ.

Arguments

  • key (chaîne de caractères)

    L’argument de champ à modifier. Il peut s’agir de l’une des propriétés décrites ci-dessus, à l’exception de $field : label, data_type, value_callback, donation_form, admin_form, show_in_meta, show_in_export, email_tag.

  • setting (chaîne de caractères)

    Ceci identifie un élément de tableau spécifique dans l'un des arguments compatibles avec les tableaux : donation_form, admin_form, email_tag. Remarque : Si $key n'est pas l'un de ces trois, laissez ceci comme une chaîne vide.

  • $value (mixte)

    La nouvelle valeur pour cet argument de champ.

Utilisation

/* Get the State field. */
$field = charitable()->donation_fields()->get_field( 'state' );

/* Change the label to Province. */
$field->set( 'label', '', 'Province' );

/* Change the field to be required. */
$field->set( 'donation_form', 'required', true );

require()

Ajouté dans la version 1.5.0

Modifiez les paramètres du champ. Contrairement à la méthode set() décrite ci-dessus, cela ne vous permet pas de mettre à jour un seul élément dans un argument de type tableau (vous ne pouvez pas l'utiliser pour modifier facilement si un champ est requis dans le formulaire de don, par exemple).

C'est l'équivalent de l'appel de set() avec l'argument $setting laissé comme une chaîne vide.

Remarque : __set() est une méthode magique en PHP. Elle est appelée implicitement lorsque vous essayez de définir l'une des propriétés de la classe, autre que $field.

Arguments

  • $key (chaîne)

    L'argument de champ à modifier. Il peut s'agir de l'une des propriétés décrites ci-dessus, à l'exception de $field : label, data_type, value_callback, donation_form, admin_form, show_in_meta, show_in_export, email_tag.

  • $value (mixte)

    La nouvelle valeur pour cet argument de champ.

Utilisation

/* Get the State field. */
$field = charitable()->donation_fields()->get_field( 'state' );

/* Change the label to Province. */
$field->label = 'Province';

require()

Ajouté dans la version 1.5.0

Obtenez la valeur du champ pour un argument particulier.

Remarque : __get() est une méthode magique en PHP. Elle est appelée implicitement lorsque vous essayez d'accéder à une propriété de classe.

Arguments

  • $key (chaîne)

    L'argument de champ à récupérer.

Utilisation

/* Get the State field. */
$field = charitable()->donation_fields()->get_field( 'state' );

/* Print/echo the current label. */
echo $field->label;

Vous avez encore des questions ? Nous sommes là pour vous aider !

Dernière modification :

Quoi de neuf dans Charitable

Voir les dernières mises à jour
🔔 Abonnez-vous pour recevoir nos dernières mises à jour
📧 Abonnez-vous aux e-mails

Abonnement par e-mail

Rejoignez notre newsletter

Nous ne vous enverrons pas de spam. Nous envoyons un e-mail uniquement lorsque nous pensons qu'il vous sera réellement utile. Désabonnez-vous à tout moment !

ambassadeurs Nouveau

🔑 Présentation des collectes sans mot de passe : inscrivez-vous avec juste une adresse e-mail !

Les donateurs arrivent en voulant aider, et ensuite le formulaire leur demande d'inventer un mot de passe pour un site web qu'ils ne visiteront peut-être que deux fois. Beaucoup d'entre eux s'arrêtent là. Les comptes de collecte sans mot de passe, nouveauté de Charitable Ambassadors 3.5.0, permettent à un donateur de lancer une collecte de pair à pair avec rien d'autre qu'une adresse e-mail. Pourquoi c'est important :

  • 🔑 Aucune étape de mot de passe pour les perdre : Activez-la dans Charitable » Ambassadeurs » Modèles » Formulaire de soumission et le formulaire de création de collecte ne demande qu'un nom, une adresse e-mail et un titre de page.
  • 👤 Toujours un vrai compte WordPress : Un clic dans un e-mail confirme l'adresse, les connecte et crée le compte, afin qu'ils puissent revenir plus tard pour modifier leur histoire, changer leur photo et voir qui a fait un don.
  • 🎚️ Votre choix pour chaque campagne : Chaque campagne de pair à pair peut suivre la valeur par défaut du site ou la remplacer, ce qui est important lorsqu'une campagne paie les collecteurs via Stripe Connect et que ces personnes ont besoin d'un mot de passe.
  • 📋 Voir qui n'a pas encore cliqué : L'onglet Charitable » Ambassadeurs » Répertoire » En attente de connexion liste tous ceux qui attendent encore, avec la campagne qu'ils ont rejointe et un bouton Réenvoyer, afin qu'une faute de frappe ou un dossier de spam puisse être repéré et corrigé.
  • 🛡️ Liens que les scanners ne peuvent pas épuiser : L'ouverture du lien n'affiche qu'une page, et votre collecteur est connecté lorsqu'il appuie sur le bouton, de sorte que les scanners d'e-mails d'entreprise n'épuisent jamais le lien. Chacun fonctionne une fois, expire de lui-même et n'est stocké que sous forme de hachage.

Consultez notre annonce ici.

ambassadeurs Nouveau

🏃 Présentation de l'activité : Montrez les progrès au-delà de l'argent !

La plupart des collectes de fonds peer-to-peer ne se résument pas à l'argent. Un marathon de lecture porte sur les minutes lues, un marathon de marche sur les kilomètres parcourus et une collecte de nourriture sur les repas préparés. L'activité pour les Ambassadeurs Caritatifs permet à vos collecteurs de fonds de montrer cet effort juste à côté des dollars qu'ils collectent. Pourquoi c'est important :

  • 🎯 Progrès sur ce que vous comptez réellement : Une barre de progression montre chaque élément que vous comptez par rapport à sa propre cible, juste à côté de l'argent collecté.
  • 🏅 Jalons pour les choses oui ou non : Un badge de jalon marque les efforts qui sont simplement faits ou non faits, sans chiffre à atteindre.
  • ✍️ Les collecteurs de fonds enregistrent leurs propres chiffres : Vos supporters saisissent leurs totaux depuis leurs propres pages, de sorte que l'effort cesse de vivre dans une feuille de calcul, un commentaire ou nulle part ailleurs.
  • 🤖 Certains chiffres se comptent eux-mêmes : Une étiquette AUTOMATIQUE apparaît partout où le site a calculé le chiffre à partir des dons complétés, afin que vous puissiez voir en un coup d'œil ce que personne n'a tapé.
  • 🧩 Configurez une fois, utilisez partout : Vous décidez ce qui est compté une fois, puis vous choisissez quelles campagnes le comptent. Disponible dès maintenant dans Charitable Ambassadors 3.4.7, sans nouveau plugin et sans développeur.

Consultez notre annonce ici.

ambassadeurs Nouveau

🖨️ Présentation des prospectus et affiches : collectez des fonds loin de l'écran !

Une grande partie de la collecte de fonds de pair à pair se fait loin d'un écran : à la ligne d'arrivée d'un 5 km, sur un panneau d'affichage d'école, dans une cuisine de bureau. Charitable Ambassadors 3.4.7 ajoute 2 imprimables, un prospectus de collecte de fonds portant la propre histoire et le code QR de chaque collecteur de fonds, et une affiche de recrutement qui inscrit de nouveaux collecteurs de fonds. Les deux s'ouvrent comme une page Web normale et s'impriment directement depuis le navigateur. Pourquoi c'est important :

  • 🏁 Un prospectus pour chaque collecteur de fonds : Chacun porte la propre photo, histoire et objectif de ce collecteur de fonds, avec un code QR qui ouvre sa page plutôt que votre campagne principale.
  • 📌 Une affiche qui recrute : Elle affiche « Recrutement en cours » au-dessus du nom de votre campagne avec un grand code QR qui ouvre votre formulaire d'inscription, afin que quelqu'un puisse commencer à collecter des fonds sans attendre un lien de votre part.
  • 🪄 Aucun outil de conception nécessaire : Les deux imprimables s'affichent comme une page Web normale et s'impriment depuis le navigateur, sans plugin PDF et sans designer.
  • 📄 2 mises en page de prospectus : « À distribuer » contient l'histoire complète pour donner à vos amis et à votre famille, et « À afficher » contient un court message accrocheur avec 5 languettes détachables pour un panneau d'affichage.
  • 🛡️ Désactivé jusqu'à ce que vous l'activiez : Les prospectus restent désactivés après la mise à jour jusqu'à ce que vous les activiez sous Charitable » Ambassadeurs » Autre » Prospectus, et seul le propriétaire ou un administrateur peut en ouvrir un.

Consultez notre annonce ici.

Amélioration Paiements

💸 Introduction des tarifs échelonnés pour l'allègement des frais : Adaptez la demande au don !

L'allègement des frais pose une courte question à vos donateurs lors du paiement : souhaitez-vous couvrir les frais de traitement de ce don ? Jusqu'à présent, cette question utilisait un taux unique pour chaque don sur une passerelle, de sorte qu'un don de 10 $ et un don de 500 $ se voyaient demander le même pourcentage. L'allègement des frais 1.3.0 vous permet de définir autant de tranches de dons que vous le souhaitez, chacune portant son propre taux. Pourquoi c'est important :

  • 🪙 Plus doux pour les petits dons : Un coût de transaction fixe représente une part beaucoup plus importante d'un don de 10 $ que d'un don de 500 $, les tranches vous permettent donc de demander moins en bas.
  • 🎚️ Autant de tranches que nécessaire : Chaque tranche porte son propre pourcentage et son propre montant fixe, et la tranche supérieure s'exécute sans limite supérieure.
  • 🛑 Un plafond facultatif : Un champ de frais maximum empêche qu'un donateur ne se voie demander plus qu'un nombre que vous choisissez, quel que soit le montant du don.
  • 🔌 Défini par passerelle de paiement : Stripe peut fonctionner avec quatre tranches tandis que Windcave et Payfast restent sur un taux unique, car les tranches appartiennent à une passerelle et non à l'ensemble de votre site.
  • 🛡️ Rien ne change tant que vous ne le décidez pas : Vos taux actuels restent exactement les mêmes jusqu'à ce que vous activiez « Utiliser les tarifs échelonnés » sous Charitable » Paramètres » Avancé » Allègement des frais.

Consultez notre annonce ici.

Dons Amélioration

📊 Votre tableau de bord Pro peut désormais comparer, exporter et évaluer !

La plupart des tableaux de bord de collecte de fonds vous indiquent seulement combien vous avez collecté. Charitable Pro 1.8.19 reconstruit le tableau de bord et la Vue d'ensemble des rapports autour des questions les plus difficiles : si quelque chose ne fonctionne pas, si cette période a été meilleure que la précédente, et quel changement unique ferait la plus grande différence aujourd'hui. Pourquoi c'est important :

  • 📈 Chaque chiffre a une tendance : Choisissez une période et les vignettes ainsi que le graphique bougent ensemble, chaque total étant affiché par rapport à la période précédente.
  • 🗓️ Des graphiques lisibles : Les courtes périodes regroupent les dons jour par jour, tandis que les longues périodes regroupent par semaine ou par mois, de sorte qu'une année complète se lit comme une courbe au lieu d'une ligne plate.
  • 🔀 Comparez n'importe quelles 2 périodes : Pas seulement consécutives, vous pouvez donc demander comment ce mois de décembre s'est comparé au mois de décembre dernier. C'est important car la collecte de fonds est saisonnière.
  • 📤 Exportez le résumé complet : Envoyez la vue d'ensemble complète en CSV ou PDF, prête pour un dossier de conseil d'administration ou un rapport de bailleur de fonds.
  • 🎯 Évaluez votre configuration gratuitement : Faites évaluer votre configuration de collecte de fonds, de sorte que le seul changement à faire ensuite soit celui que vous pouvez voir.

Consultez notre annonce ici.