Adding a custom text field to a donation form

Thanks to Charitable’s internal API, donation forms can be customized in a variety of ways. One of the most requested features is adding one or more custom fields to Charitable’s donation form. In this post, we’ll show you how to add a new field – a text field – to your donation forms using Charitable.

Even if you’re not a developer, you can still add code snippets pretty easily. You have the option to install a code snippet plugin of your choice, but since Charitable works great with WPCode, we’ll assume you’re using that for this post.

Note: If you’re a developer, you’ll know that code snippets can be added to a WordPress theme’s functions.php or within a custom plugin. If you go this route, we recommend following our guide on best practices for writing code with Charitable. You should also read our Charitable_Donation_Field documentation.

Using WPCode

The first step is to install WPCode itself. You can install and activate the free version like any other WordPress plugin. However, Charitable has a simpler built-in process. Please read our documentation on how to install and browse code snippets with WPCode.

Code snippet library

All the code snippets we share in this post are present in the Charitable Code Library at WPCode. You don’t have to use WPCode to use the code snippets and examples in this library. You can copy and paste various code examples of your choice from the plugin into your text editor or other application. So, we recommend you to bookmark: Charitable Code Library at WPCode.

Adding a text box

In our first example, we’ll start with a simple text box for our donation form. Search for “text box” on Charitable’s code snippets page in the plugin, or copy and paste the code below into your code editor.

This code exists here in the Charitable 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’ );

These are the most important fields to customize:

• label. Change the text “My Custom Field” in the quotes to whatever statement you want donors to see on the public donation form.
• Donation_form -> Type. This is the type of donation field (text, select, checkbox, date picker, etc.). For a full list of supported donation field types, see our documentation.
• 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 in this field in your email using an email tag in Charitable, add a description here to show it in the email settings. By default, Charitable uses the key value as the tag (in this case, “my_custom_field”).

Once this code (via the Charitable Snippet screen or by copying and pasting the code) is in WPCodegive it a descriptive title, make sure the code type is “PHP Snippet” and that you have “Auto-Insert/Execute Everywhere” selected. Activate the snippet.

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

You should see something like this:

Congratulations! You have added your referral code text box. 🎉

Display custom data in a donation

As a reminder, if you set admin_form to true in your snippet, you will be able to show this information in any donation edit screen. If show_in_export was set to true in the snippet above, you should also see this value in the CSV donation data exported to Charitable.

outlook

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

Please let us know if you would like posts or documentation on a specific topic and feel free to contact support! We appreciate your feedback!

David has been a Project Manager at Charitable since 2022. David works with several nonprofits (one of which is run by his wife) and manages and develops features, support, and marketing for Charitable. He has been with WordPress since 2006 and has been a lead organizer of several conferences, events, and meetups.

Disclosure: Our content is supported by our readers, which means when you click on some of our links, we may earn a commission. We only recommend products that we believe will add value to our readers.