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
La clé ou l'identifiant du champ. Chaque champ doit avoir une clé unique.
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 estcharitable_get_donor_meta_value. - Pour un champ
user, le rappel de valeur par défaut estcharitable_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.
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élabeldu champ sera utilisée.type (string)Le type de champ. Les options incluent :texteemailmot de passedatesélecteur de datecase à cochercases à cocher multiplessélectionnerradiofichiergroupe de champséditeur(utilise l'éditeur WordPress classique)zone de textenombreimageurlcaché
requis (booléen)Indique si ce champ est obligatoire.options (tableau)Fournit un ensemble d'options. Ceci est requis lorsquetypeest l'un desélectionner,radiooucases à 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 sitypeestnombre.max (int)Définit le nombre maximum autorisé. Applicable uniquement sitypeestnombre.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 :utilisateuretmé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 sishow_afteroushow_beforesont définis pour le champ. Sipriority,show_afteretshow_beforene 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ètrevalue_callbackpour le champ.
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 dedonation_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_formci-dessus).
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.
Indique s’il faut inclure ce champ dans l’exportation des dons disponible dans Charitable > Dons.
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’étiquettedu 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$keyn'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;
