The Charitable_Donation_Field class allows you to create new donation fields or edit existing ones.
Table of Contents
Usage
Create a new donation field
If you want to add a new donation field, you will first need to create a new Charitable_Donation_Field instance, and then register it in the Donation Fields Registry.
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 );
} );Get an existing donation field
If you want to edit or change an existing donation field, the best way to do this is by getting the registered donation field object.
You can then use set() or the magic setter to update the field definition, or use the magic getter to get information about the field.
/* 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;Properties
The field’s key, or identifier. Every field must have a unique key.
The field’s label. This is a description of the field. This is what will be used in the donation form (unless you specifically override it in the donation_form argument), in the admin donation details area and in the donations export as the column header.
The type of data that this field represents. There are two main options, with a third used mostly for internal Charitable purposes:
user: This is information that is specific to the donor, and will generally remain true for the donor in subsequent donations. Examples of this would include their name, phone number, etc.meta: This is information that is specific to the donation. An example of this would be the payment gateway used for the donation, or whether the donor would like this donation to be made anonymously.core: This is used primarily for internal purposes and should not be used in most cases. If you do use it, you will need to make sure you write additional code for storing the field value, as well as for getting it back from the database.
value_callback (false|callable)
How the field’s value will be retrieved. If you leave this out or set it to false, the default callback will be used based the field’s data type:
- For a
metafield, the default value callback ischaritable_get_donor_meta_value. - For a
userfield, the default value callback ischaritable_get_donation_meta_value.
You can specify your own value callback by passing your own function’s name, an array representing an object method [$class_name, $method_name], or an anonymous function.
How/whether the field will be included in the donation form. If this is left out or set to false, the field will not be included in the donation form at all. When passing an array, the following arguments are available:
label (string)
The label shown in the donation form. If this is left out, the field’slabelproperty will be used.type (string)The type of field. Options include:textemailpassworddatedatepickercheckboxmulti-checkboxselectradiofilefieldseteditor(uses the classic WordPress Editor)textareanumberpictureurlhidden
required (boolean)Whether this is a required field.options (array)Provide a set of options. This is required whentypeis one ofselect,radioormulti-checkbox. These should be provided in a simple value => label array, where the label is what people see when they select an option, and value is what gets stored in the database.default (mixed)
The default value for this field.placeholder (string)A placeholder shown in the field when it’s empty.min (int)Set the minimum allowed number. Only applicable iftypeisnumber.max (int)Set the maximum allowed number. Only applicable iftypeisnumber.attrs (array)
An array of arbitrary attributes to be added to the input field.section (string)
The section of the donation form this should appear in. There are two sections by default:userandmeta. If this is not set, the section will be based on the field’s data type.show_before (string)
Sets where the field should be added in the donation form by specifying the field it should appear before.show_after (string)
Sets where the field should be added in the donation form by specifying the field it should appear after.priority (int)
Set the position of the field within the form. This is used unlessshow_afterorshow_beforeare set for the field. Ifpriority,show_afterandshow_beforeare not set, the field will be shown after the most recently registered form field.value_callback (false|callable)
A callback function to retrieve the value of the field for a donation. This will override thevalue_callbacksetting for the field.
Sets whether the field should be shown in the admin donation form.
- If this is set to
false, the field will not be shown in the admin donation form (not even as a hidden input). - If this is set to
true, the form field will inherit arguments from thedonation_form(if provided), or use default arguments. - Alternatively, you can pass an array of values to fine-tune how this field is shown in the admin form (all the same arguments are accepted as for
donation_formabove).
Whether to include this in the “Donation Details” section of a single donation details admin page.
Whether to include this in the Donations export available from Charitable > Donations.
Whether to create an email tag for this field.
- If this is
false, no email tag will be created. - If this is
true, an email tag will be created, using the field label as the description. No preview value will be set. - Alternatively, pass an array for finer control over the email tag details:
description (string)
The description shown for the email tag. If no description is set, the field’slabelwill be used.tag (string)
The email tag. If this is not provided, the field key will be used.preview (mixed)
A value to use in email previews for this field.
Methods
require()
Added in version 1.5.0
Create a new Donation Field instance.
Arguments
$field (string)The field’s unique key.
$args (array)An array containing any of the properties shown above, except for
$field.
Usage
$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()
Added in version 1.6.0
Change a field argument.
Arguments
key (string)The field argument to change. This can be any of the properties outlined above, except for
$field:label,data_type,value_callback,donation_form,admin_form,show_in_meta,show_in_export,email_tag.setting (string)This identifies a specific array element within one of the array-compatible arguments:
donation_form,admin_form,email_tag. Note: If$keyis not one of those three, leave this as an empty string.$value (mixed)The new value for this field argument.
Usage
/* 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()
Added in version 1.5.0
Change the field’s parameters. Unlike the set() method described above, this does not allow you to update a single element within an array-like argument (you can’t use it to easily change whether a field is required in the donation form, for example).
It’s the equivalent of calling set() with the $setting argument left as an empty string.
Note: __set() is a magic method in PHP. It is called implicitly when you try to set one of the class properties, other than $field.
Arguments
$key (string)The field argument to change. This can be any of the properties outlined above, except for
$field:label,data_type,value_callback,donation_form,admin_form,show_in_meta,show_in_export,email_tag.$value (mixed)The new value for this field argument.
Usage
/* Get the State field. */ $field = charitable()->donation_fields()->get_field( 'state' ); /* Change the label to Province. */ $field->label = 'Province';
require()
Added in version 1.5.0
Get the field’s value for a particular argument.
Note: __get() is a magic method in PHP. It is called implicitly when you try to access a class property.
Arguments
$key (string)The field argument to retrieve.
Usage
/* Get the State field. */ $field = charitable()->donation_fields()->get_field( 'state' ); /* Print/echo the current label. */ echo $field->label;
