While most people use Charitable for fundraising campaigns, some users have found creative uses for it. One customer recently wanted to continue using Charitable as a donation tool, while also using it as a way for people to register for their event.

The first step to achieving this is easy enough: Just create a separate campaign for the event registration. You can configure different ticket prices by using the Suggested Donations feature — simply set a price and a description.

But the challenge comes when you want to make the form button text more appropriate for the context. Instead of “Donate”, this should say something like “Purchase Tickets”.

In this tutorial, I will show you how you can use a little bit of custom code to easily customize the Donate button text on a per-campaign basis.

La solution

To achieve this, we’re going to register a new field in the Campaign editor in the WordPress dashboard. This field will allow you to specify what the Donate button text should be.

We are also going to create modified versions of templates where the Donate button is shown; these will be stored in our theme or child theme folder and will override the default templates included in Charitable.

Step 1: Add our function

If you read my last tutorial, this step will be familiar to you.

We’re going to add a PHP function which will be run when the init hook is called within WordPress. init is a hook that happens early on while WordPress is loading, before the page has started rendering.

add_action( 'init', function() {
    // Our code will go in here.
} );

We are using an anonymous function here, which is fine as long as you are on a version of PHP greater than 5.2.

If you’re not sure how to add this to your site, check out our guide:

3 façons d'ajouter des personnalisations de code à votre site

Step 2: Add the field to the Campaign editor

Next up, we will use the Campaign Fields API to add a “Button Text” field to the Campaign editor.

add_action( 'init', function() {

    /**
     * Create a new field as an instance of `Charitable_Campaign_Field`.
     *
     * See all available arguments at:
     *
     * @https://github.com/Charitable/Charitable/blob/ef9a468fbdd6fa83307abe6ac0c38896f625cf45/includes/fields/class-charitable-campaign-field.php
    */
    $campaign_field = new Charitable_Campaign_Field( 'button_text', array(
    'label'          => 'Button Text',
    'data_type'      => 'meta',
    'admin_form'     => array(
        'type'     => 'text',
        'required' => false,
        'default'  => 'Donate',
    ),
    'value_callback' => function( Charitable_Campaign $campaign, $key ) {
        $text = $campaign->get_meta( '_campaign_button_text' );

        // Set a default value to use when the button text is not set yet.
        if ( empty( $text ) ) {
            $text = 'Donate';
        }

        return $text;
    },
    ) );

    /**
     * Now, we register our new field.
     */
    charitable()->campaign_fields()->register_field( $campaign_field );

} );

In this code, we first of all create a new field by creating a Charitable_Campaign_Field object. We pass two parameters when creating this object:

– A key – button_text
– An array of arguments

We’re only using a sub-set of all the arguments that are possible when registering a campaign field. To see other arguments that are available, read the exhaustive inline documentation on Github.

One important argument included here is the value_callback parameter:

'value_callback' => function( Charitable_Campaign $campaign, $key ) {
    $text = $campaign->get_meta( '_campaign_button_text' );

    // Set a default value to use when the button text is not set yet.
    if ( empty( $text ) ) {
        $text = 'Donate';
    }

    return $text;
},

This is a function which will be used to get the value of the field for a particular campaign. We include it here to provide a default value of “Donate” for the button_text field; this is needed for existing campaigns that have not been saved since this campaign field was added.

If we go to add a new campaign or edit an existing one, we will now see an “Extended Settings” panel, and inside that is a “Button Text” field.

Step 3: Override the donation form template

Inside of Charitable you will see a templates directory. All templates in this directory can be overridden by creating a copy in your child theme folder. If you’re not using a child theme, you can also override them by creating a copy in your theme folder, but we recommend the child theme approach since it ensures you won’t lose your changes when updating your theme in the future.

First of all, we will create a charitable folder inside of our child theme folder. Whenever you want to override a template inside Charitable’s templates directory, it needs to be stored in the same relative location inside of the charitable folder (without templates).

In our case, we want to override the donation-form/form-donation.php template. Here’s how we do that:

• In our child theme, we create a new file at charitable/donation-form/form-donation.php.
• Into this, we paste the contents of the templates/donation-form/form-donation.php file in Charitable.

If you save this file and reload your donation form, you won’t notice any differences — that’s because we haven’t changed anything yet! So let’s get on to copying in our custom button text.

In the template, look for the following line:

<button class="button button-primary" type="submit" name="donate"><?php _e( 'Donate', 'charitable' ); ?></button>

In the current version of Charitable (1.6.13), this is located on line 59 but this may change in the future. The bit we need to replace is this part in the middle: <?php _e( 'Donate', 'charitable' ); ?>.

Our custom button text can be retrieved by getting the form campaign object with $form->get_campaign(), and then calling using the get( 'button_text' ) on that:

<?php echo $form->get_campaign()->get( 'button_text' ); ?>

Put together, the updated line looks like this:

<button class="button button-primary" type="submit" name="donate"><?php echo $form->get_campaign()->get( 'button_text' ); ?></button>

Now when you reload the donation form, it will show your campaign’s custom button text.

Step 4: Rinse & repeat for other templates

Step 3 fixed the donation form. But the “Donate” button appears in a couple other cases too:

• In a list or grid of campaigns when you’re using the [campaigns] shortcode.
• On the campaign page itself.

Determining the templates you need to override

Which templates you need to override depends on how you have set your donation form to appear with the “Display Options” setting under Charitable > Settings.

“Show on a Separate Page”

The two templates you need to override are:

• templates/campaign/donate-button.php
• templates/campaign-loop/donate-link.php

Copy and paste the contents of these two files into your child theme at:

• charitable/campaign/donate-button.php
• charitable/campaign-loop/donate-link.php

“Show on the Same Page”

The two templates you need to override are:

• templates/campaign/donate-link.php
• templates/campaign-loop/donate-link.php

Copy and paste the contents of these two files into your child theme at:

• charitable/campaign/donate-link.php
• charitable/campaign-loop/donate-link.php

“Reveal in a Modal”

The two templates you need to override are:

• templates/campaign/donate-modal.php
• templates/campaign-loop/donate-modal.php

Copy and paste the contents of these two files into your child theme at:

• charitable/campaign/donate-modal.php
• charitable/campaign-loop/donate-modal.php

Making the changes

Depending on which template you are overriding, the actual bit you need to change is either:

<?php _e( 'Donate', 'charitable' ); ?>

Or:

<?php esc_attr_e( 'Donate', 'charitable' ); ?>

To change the first variety (i.e. _e), replace it with this:

<?php echo $campaign->get( 'button_text' ); ?>

If you’re changing the second variety (i.e. esc_attr_e), swap it with this:

<?php echo esc_attr( $campaign->get( 'button_text' ) ); ?>

Wrapping up

Now that you have updated all of the templates, you should see that your custom campaign button text is used wherever a Donate button is displayed. All we had to do to get there is create a new campaign field and modify three default templates using our child theme.

If you’ve been following along, I hope you can see how the flexibility of the Campaign Fields API, this process can be used to make many more tweaks to how Charitable works on your website. For example, you could adapt this process to add a campaign-specific blurb before the donation form; it just requires creating a new campaign field and adding the value of that field to the form-donation.php template (i.e. steps 2 & 3).

Found this helpful? Any questions? I’d love to hear from you; send us an email via our Support page or leave a comment below. If you have a suggestion for a topic you would like to see me cover in a future tutorial, we’d love to hear about that, too. 🙂