Skip to content
Documentation › The Email Fields API

The Email Fields API

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, callback will 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 the show parameter but may include other arguments if these are applicable to the email tag.
  • $email: An instance of Charitable_Email. You can use this to get the objects associated with the email (usually one of Charitable_Campaign, Charitable_Donation or Charitable_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' );

Categories