Charitable donation forms can be customized in various ways thanks to Charitable’s internal API. One of the most requested features is to add one or more custom fields to the Charitable donation form. In this post we are going to show you how you can add a new field – a textbox – to your donation forms using Charitable.

Even if you’re aren’t a developer, adding code snippets are easy to do. You have the option of installing a code snippet plugin of your choice but since Charitable works great with WPCode… we will assume you are using that for this post.

Note: If you ARE a developer then you are aware code snippets can be added to the functions.php of a WordPress theme or within it’s own plugin… if you go down this route we recommend you follow our instructions on best practices for writing code with Charitable. You should also be reading our Charitable_Donation_Field documentation.

Using WPCode

The first step is to install WPCode itself. You can install and activate the free version just like you can with any other WordPress plugin. However, Charitable has an easier built-in process. Please read our documentation on installing and browsing code snippets with WPCode.

Code Snippet Library

All the code snippets we will share in this post exist in the Charitable’s code library at WPCode. You don’t have to use WPCode to take advantage of the code snippets and examples in this library… you can copy and paste various code samples of your choice from the plugin into your text editor or other application. So we recommend you bookmark: Charitable’s code library at WPCode.

Adding A Text Field

In our first example we are going to start off with with a simple textbox to our donation form. Search for “textbox” in Charitable’s code snippet page in the plugin or copy and paste the code below into your code editor.

This code exists here in Charitable’s code library at WPCode.

/**
 * Shows how to add a custom text box in a donation form.
 * In this example, we are adding a text box to collect a special referral code that the admin can read later.
 *
 * This snippet only works in Charitable 1.5 or above.
 *
 */
function wpchar_charitable_register_new_text_field() {
    /**
     * Define a new text field.
     */
	
	if ( ! class_exists("Charitable_Donation_Field" ) ) {
		return;
	};
		
    /* Create the Donation Field instance. */
    $field = new Charitable_Donation_Field(
        'my_custom_field',
        array(
            'label'          => __( 'Referral Code' ), // what text shows up in the donation form.
            'data_type'      => 'meta', 
            'value_callback' => false,
            'donation_form'  => array(
                'type'       => 'text',  // the type of field to show in the donation form (text, checkbox, etc.)
                'required'   => false,   // whether the field is required.
                'show_after' => 'phone', // the field to show this one after.
            ), 
            'admin_form'     => true,
            'show_in_meta'   => true,
            'show_in_export' => true,
            'email_tag'      => array( // the tag to use in email notifications (make false to not add this to tags.
                'description' => __( 'The custom field value' ),
            ),
        )
    );

    /* Register it. */
    charitable()->donation_fields()->register_field( $field );

}

add_action( 'init', 'wpchar_charitable_register_new_text_field' );

Here are the key fields to customize:

• Label. Change the “My Custom Field” text within the quotes to what you want this to say to donors who see this field in the public donation form.
• donation_form -> type. This is the type of donation field (text, select, checkbox, datepicker etc.). See our documentation for a full list of supported donation field types.
• donation_form -> required. If you want this field to be required, set it to true.
• email_tag. If you want to include the value entered into this field in your email with an email tag in Charitable, add a description here so you can see it appear in the email settings. By default, Charitable uses the key value as the tag (‘my_custom_field’ in this case).

Once this code (via the Charitable snippet screen or by copy and pasting the code) is in WPCode, make sure you give it a descriptive title, make sure the code type is “PHP snippet”, and that you’ve selected auto-insert/run everywhere. Make the snippet active/enabled.

One this is active, visit a donation form (either generated automatically by Charitable or via a shortcode).

You should see something like this:

Congrats! You’ve added your referral code textbox. 🎉

Viewing Custom Data In A Donation

As a reminder, if you have “admin_form” true in your snippet you can view this information in any donation edit screen. If “show_in_export” was left true in the snippet above, you should also see this value exported in the CSV donation data in Charitable as well.

Looking Ahead

If you are a developer or comfortable with adding the code above you should check out our Charitable_Donation_Field documentation and the Donation Fields API for additional and deeper customization… and don’t forget to browse Charitable’s code library at WPCode.

Please let us know if you want any posts or documentation upon a particular subject and feel free to reach out to support! We would love to hear feedback!

David Bisset Project Manager

David is the project manager of Charitable since 2022. David works with several non-profits (one operated by his wife) along with managing and developing features, support, and marketing for Charitable. Has been with WordPress since 2006 and has been lead organizer of multiple conferences, events, and meetups.

See Full Bio