Skip to content

Hooks and filters in Ambassadors

Please note: This documentation is a work in progress and does not yet cover all filters & action hooks available in Charitable Ambassadors. If you do not see a hook or filter describing what you need to do, please get in touch via our support page and we can help you.

Filters

charitable_ambassadors_fundraiser_title

Added in version 2.0.0

Change the automatically generated title for a new fundraiser, when the title is set to be dynamically based on the campaign creator’s name.

Return Value

String. The title of the fundraiser.

Arguments

  • $title (string)

    The title. By default this will be the campaign creator’s full name.

  • $data (array)

    The submitted data.

Usage

add_filter( 'charitable_ambassadors_fundraiser_title', function( $title, $data ) {
    $first_name = array_key_exists( 'first_name', $data ) ? $data['first_name'] : '';
    $last_name  = array_key_exists( 'last_name', $data ) ? $data['last_name'] : '';
    $full_name   = trim( sprintf( '%s %s', $first_name, $last_name ) );

    // Joe Blow's Fundraiser
    return sprintf( "%s's Fundraiser", $full_name );
}, 10, 2 );

Added in version 2.0.0

Choose whether you want to show the “Create a New Campaign” button at the bottom of the output of the [charitable_my_campaigns] shortcode.

Return Value

Boolean. True if you do want to show it, or false if you would prefer not to. This will return true by default.

Arguments

  • $show (boolean)

    Whether to show the button.

Usage

// Do not show the button.
add_filter( 'charitable_ambassadors_my_campaigns_show_campaign_creation_link', '__return_false' );

charitable_ambassadors_my_campaigns_button_text

Added in version 1.0.0

Change the text of the “Create a Campaign” button at the bottom of the [charitable_my_campaigns] shortcode.

Return Value

String. The text to use in the button.

Arguments

  • $text (string)

    The button text.

Usage

add_filter( 'charitable_ambassadors_my_campaigns_button_text', function( $text ) {
    return 'Start a New Campaign';
} );

Added in version 1.0.0

Change the page that users will be redirected to after they submit their campaign for the first time. Note that if you want to redirect to a static page, you can do this without code by configuring the “Campaign Submission Success Page” setting under Charitable > Settings > Ambassadors.

Return Value

String. A URL to redirect to after first submitting a campaign. Note that the redirect is done through a call to wp_safe_redirect(), so the URL should be to an allowed host (see https://developer.wordpress.org/reference/functions/wp_safe_redirect/).

Arguments

  • $default (string)

    The URL to redirect to.

  • $args (array)

    An array of arguments. By default, this will only have a campaign_id property with the ID of the newly submitted campaign.

Usage

// Redirect to the newly submitted campaign after submission.
add_filter( 'charitable_permalink_campaign_submission_success_page', function( $url, $args = array() ) {
    if ( ! array_key_exists( 'campaign_id', $args ) ) {
        return $url;
    }

    return get_permalink( $args['campaign_id'] );
}, 10, 2 );

charitable_campaign_submission_redirect_url

Added in version 1.0.0

Change the URL that users are redirected to after they submit, update or save & preview their campaign.

If you only want to change the page that users are redirected to after they first submit their campaign, use the charitable_permalink_campaign_submission_success_page filter instead.

Return Value

String. The URL that the user will be redirected to.

Arguments

  • $url (string)

    The URL that the user will be redirected to.

  • $data (array)

    The submitted data.

  • $campaign_id (int)

    The campaign ID.

  • $user_id (int)

    The user ID.

charitable_ambassadors_fundraiser_form_field_list

Added in version 2.1.0

Add or remove fields to the fundraiser form.

The fields list is a list of keys of fields that are included in the main campaign form, which should also be included in the fundraiser form. The following fields are not included in the fundraiser form by default:

description
categories
tags
suggested_donations
allow_custom_donations

Return Value

array

Arguments

  • $list (array)

    The list of fields to be included.

  • $form (Charitable_Ambassadors_Fundraiser_Form)

    The fundraiser form object.

Usage

// Include the 'description' field in the Fundraiser form.
add_filter( 'charitable_ambassadors_fundraiser_form_field_list', function( $fields ) {
    $fields[] = 'description';
    return $fields;
} );

charitable_ambassadors_fundraiser_inherited_fields

Added in version 2.0.0

Filter the fields that are automatically inherited from the fundraiser’s parent campaign.

Return Value

array

Arguments

  • $fields (array)

    The inherited fields.

Usage

add_filter(
    'charitable_ambassadors_fundraiser_inherited_fields', 
    function( $fields ) {
        $fields[] = 'my_custom_field';
        return $fields;
    }
);

charitable_ambassadors_update_fundraiser_end_dates_on_parent_end_date_change

Added in version 2.0.0

Set whether end dates of fundraisers should be updated automatically when a parent campaign has its end date changed.

Return Value

Boolean. Defaults to true.

Arguments

  • $should_update (boolean)

    Whether to update automatically.

  • $campaign (Charitable_Campaign)

    The parent campaign object.

charitable_ambassadors_creator_donations_export_columns

Added in version 2.0.0

Filter the columns that are included in the export.

Return Value

Array. The keys of columns to include.

Arguments

  • $columns (array)

    The columns to include.

Usage

add_filter( 'charitable_ambassadors_creator_donations_export_columns', function( $columns ) {
    // Only show the first name, last name, amount and donor comment.
    $included_columns = array(
        'first_name',
        'last_name',
        'amount',
        'donor_comment',
    );
	
    foreach ( $columns as $column => $header ) {
        if ( ! in_array( $column, $included_columns ) ) {
            unset( $columns[ $column ] );
        }
    }
	
    return $columns;
} );