How to add checkboxes to your 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 some examples of adding custom fields with code snippets.

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.

Remember that once added (via the Charitable Snippet screen or by copying and pasting the code) in WPCode You need to give it a descriptive title, make sure the code type is “PHP Snippet” and that you have selected “Auto-insert/execute everywhere”. Activate the snippet. Here is an example:

Adding a checkbox

The code snippet for a single checkbox is not much different from a textbox. Note the use of “checkbox” as the “type”. You can also view this code in our WPCode snippets library.

/**
 * Collect a checkbox field in the donation form.
 *
 * This snippet only works in Charitable 1.5 or above.
 *
 * Related examples:
 *
 * @see Register a text field (detailed example) - https://github.com/Charitable/library/blob/master/donation-form/register-new-donation-field-1.5.php
 * @see Register multiple fields - https://github.com/Charitable/library/blob/master/donation-form/register-multiple-donation-fields.php
 * @see The old way to add fields - https://github.com/Charitable/library/blob/master/donation-form/legacy/add-checkbox-field-to-donation-form.php
 */
function wpchar_charitable_register_new_checkbox_field() {
	
	if ( ! class_exists("Charitable_Donation_Field" ) ) {
		return;
	};
	
    /**
     * Define a new checkbox field.
     */
    $field = new Charitable_Donation_Field( 'new_checkbox_field', array(
        'label' => __( 'New Checkbox Field', 'charitable' ),
        'data_type' => 'user',
        'donation_form' => array(
            'type' => 'checkbox',
            'show_before' => 'phone',
            'required'   => false,
        ),
        'admin_form' => true,
        'show_in_meta' => true,
        'show_in_export' => true,
        'email_tag' => array(
            'description' => __( 'The new checkbox field' , 'charitable' ),
        ),
    ) );

    /**
     * Register the checkbox field.
     */
    charitable()->donation_fields()->register_field( $field );
}

add_action( 'init', 'wpchar_charitable_register_new_checkbox_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.

Once this is active, visit a donation form (either automatically generated by Charitable or via a shortcode) and you should see your checkbox. 🎉

Multiple checkboxes

To add multiple checkboxes, you need to add “Options” to the snippet and change the type to “Multiple Checkboxes”.

The following script adds MULTIPLE checkboxes (using “multi-checkbox” and can also be found in our WPCode snippet library. You can also check out other, more practical examples of using checkboxes that add a bit more logic, like this example of adding a checkbox to disable donation receipts.

/**
 * Add three checkboxes (the same group) in the donation form.
 *
 * This snippet only works in Charitable 1.5 or above.
 *
 */
function wpchar_charitable_register_new_checkboxes_field() {
	
    if ( ! class_exists("Charitable_Donation_Field" ) ) {
	return;
    };
	
    /**
     * Define a new checkbox field.
     */
    $field = new Charitable_Donation_Field( 'new_checkboxes_field', array(
        'label' => __( 'New Checkboxes Field', 'charitable' ),
        'data_type' => 'user',
        'donation_form' => array(
            'type' => 'multi-checkbox',
            'show_before' => 'phone',
            'required'   => false,
            'options' => array (
                 'option_1_value' => 'Option One',
                 'option_2_value' => 'Option Two',
                 'option_3_value' => 'Option Three',
	     ),
        ),
        'admin_form' => true,
        'show_in_meta' => true,
        'show_in_export' => true,
        'email_tag' => array(
            'description' => __( 'The new checkbox field' , 'charitable' ),
        ),
    ) );

    /**
     * Register the checkbox field.
     */
    charitable()->donation_fields()->register_field( $field );
}

add_action( 'init', 'wpchar_charitable_register_new_checkboxes_field' );

This should look like this on your donation form: