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 a few examples of adding custom fields with code snippets.
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.
Remember that once is added (via the Charitable snippet screen or by copy and pasting the code) in WPCode you need 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. Here’s an example:
Adding A Checkbox
The code snippet for a single checkbox is not that different from a text box. Notice the use of “checkbox” as the “type”. You can also view this code on our WPCode snippet 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' );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) and you should see your checkbox. 🎉
Multiple Checkboxes
Adding multiple checkboxes requires adding “options” to the snippet and changing the type to “multi-checkbox”.
The below script adds MULTIPLE CHECKBOXES (using “multi-checkbox” and can also be found in our WPCode snippet library and you can also view another more real world examples of using checkboxes that add a bit more logic, like this example of adding a donation receipt opt out checkbox.
/**
* 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 appear like this in your donation form:
Leave a Reply