The Email Fields API was introduced in version 1.5 and provides a cleaner way to add new email tags or modify existing ones.
Defining a Field
An email field is defined as an array with a few arguments, and a key which is used for the show parameter in the [charitable_email] shortcode.
Arguments
description: The description that will be shown for the email tag.preview: The placeholder value that will be used for this email tag in email previews.callback: A function that will be executed to get the tag value for a particular email.value: A fixed value for the email tag. If this is set,callbackwill not be used and is not required.
In addition, an email field has a key which will be used when the tag is added.
Callback arguments
The callback function will receive three arguments:
$value: The default value (an empty string). This is provided primarily for backwards-compatibility purposes.$args: The shortcode arguments. This will always include theshowparameter but may include other arguments if these are applicable to the email tag.$email: An instance ofCharitable_Email. You can use this to get the objects associated with the email (usually one ofCharitable_Campaign,Charitable_DonationorCharitable_User).
Adding a Campaign email field
Campaign email fields can be added using the charitable_email_campaign_fields filter:
function ed_charitable_email_campaign_field_callback( $value, $args, $email ) {
$campaign = $email->get_campaign();
return $campaign->get( 'some_field' );
}
function ed_charitable_add_email_campaign_field( $fields ) {
$fields['some_field'] = array(
'description' => 'A description of this field',
'preview' => 'Placeholder value',
'callback' => 'ed_charitable_email_campaign_field_callback',
);
return $fields;
}
add_filter( 'charitable_email_campaign_fields', 'ed_charitable_add_email_campaign_field' );
Adding a Donation email field
Donation email fields can be addd using the charitable_email_donation_fields filter:
function ed_charitable_email_donation_field_callback( $value, $args, $email ) {
$donation = $email->get_donation();
return $donation->get( 'some_field' );
}
function ed_charitable_add_email_donation_field( $fields ) {
$fields['some_field'] = array(
'description' => 'A description of this field',
'preview' => 'Placeholder value',
'callback' => 'ed_charitable_email_donation_field_callback',
);
return $fields;
}
add_filter( 'charitable_email_donation_fields', 'ed_charitable_add_email_donation_field' );
Adding a User email field
Defining a new user email field follows the exact same process, but with the charitable_email_user_fields filter:
function ed_charitable_email_user_field_callback( $value, $args, $email ) {
$user = $email->get_user();
return $user->get( 'some_field' );
}
function ed_charitable_add_email_user_field( $fields ) {
$fields['some_field'] = array(
'description' => 'A description of this field',
'preview' => 'Placeholder value',
'callback' => 'ed_charitable_email_user_field_callback',
);
return $fields;
}
add_filter( 'charitable_email_user_fields', 'ed_charitable_add_email_user_field' );
Modifying Existing Email Fields
Existing email fields can also be changed with these filters. For example, you can use this to change the callback for an existing tag, or to edit the description.
Changing a field’s callback
function ed_charitable_donor_address_email_field_callback( $value, $args, $email ) {
// Return the donor's address.
}
function ed_charitable_set_donor_address_email_field_callback( $fields ) {
$fields['donor_address']['callback'] = 'ed_charitable_donor_address_email_field_callback';
return $fields;
}
add_filter( 'charitable_email_donation_fields', 'ed_charitable_set_donor_address_email_field_callback' );
Changing a field’s description
function ed_charitable_set_user_login_email_field_description( $fields ) {
$fields['user_login']['description'] = 'My user login description';
return $fields;
}
add_filter( 'charitable_email_donation_fields', 'ed_charitable_set_user_login_email_field_description' );
