Often times you may want to add one or many custom form fields to one or many donation forms. Give has many hooks that developers can use to insert content, including custom fields, within donation forms. The following article will help developers programmatically add custom form fields and display them within the donation payment records.

Looking for a non-code method to add form fields? Check out the Form Field Manager Add-on for a quick and easy way to add custom form fields.

How to Add a Custom Field

A Custom Textarea in the form
A Custom Textarea in the form

Let’s say you have a specific donation form that you would like to ask donors how they were referred. The field we are going to add will be a single textarea to a specific form. We will specify the form by it’s ID using a series of conditional checks.

First, we will use the appropriate Give hook so we can output our field in the proper place. Keep in mind, you can add any type of field or content using Give’s hooks. For this example, I think our custom field will go great beneath the donation levels fields. To have it displayed in this placement I will use the give_after_donation_levels action: (there’s a full-ish list of available actions embedded in this blog post)

NOTE: This snippet is not yet using new Give 2.0 functions. While it may still work with our deprecated code; we encourage developers to dig into using updated 2.0 functions and we’ll be updating these examples soon.

First, Add the Form Field(s) by Hooking in Appropriately

/**
 * Add Custom Donation Form Fields
 *
 * @param $form_id
 */
function give_myprefix_custom_form_fields( $form_id ) {
	// Only display for forms with the IDs "754" and "578";
	// Remove "If" statement to display on all forms
	// For a single form, use this instead:
	// if ( $form_id == 754) {
	$forms = array( 754, 578 ); ?>
    <div id="give-referral-wrap">
        <label class="give-label" for="give-referral"><?php _e( 'How did you hear about GDI?:', 'give' ); ?> <span
                    class="give-tooltip icon icon-question"
                    data-tooltip="<?php _e( 'Please take a second to tell us how you first heard about Girl Develop It.', 'give' ) ?>"></span>
        </label>
        <textarea class="give-textarea" name="give_referral" id="give-referral"></textarea>
    </div>
	<?php
// endif;
}

add_action( 'give_after_donation_levels', 'give_myprefix_custom_form_fields', 10, 1 );

Notice in our code above that we have wrapped our field output within a conditional “if” statement. This is because we want to ensure our field is only output on a specific donation form. If we wanted to create a global field that would show up on all forms we would simply omit this conditional check.

Optional: Validate the New Field

Depending on the field you have added, you may want to ensure it’s completed prior to the user being able to complete their donation. Give makes it easy to customize our validation checks with the use of the give_donation_form_required_fields action:

Validate Custom Form Fields

/**
 * Validate the Custom Field
 *
 * Check for errors without custom fields
 *
 * @param $valid_data
 * @param $data
 *
 * @return mixed
 */
function give_myprefix_validate_custom_fields( $valid_data, $data ) {
	// Only validate the form with the IDs "754" and "578";
	// Remove "If" statement to display on all forms
	// For a single form, use this instead:
	// if ( $form_id == 754) {
	$forms = array( 754, 578 );
//	if ( in_array( $form_id, $forms ) ) {
	$required_fields['give_referral'] = array(
		'error_id'      => 'invalid_give_referral',
		'error_message' => __( 'Please tell us how you heard about Girl Develop It.', 'give' ),
	);

//	}

	return $required_fields;
}

add_filter( 'give_donation_form_required_fields', 'give_myprefix_validate_custom_fields', 10, 2 );

Notice: we also have a conditional check to see if we are on our specific form containing the custom “referral” field prior to validation. This is important, because if we were to leave this conditional check out all other donation forms would be checking for a field that isn’t there and would never submit. So, be sure you have your form ID checks in place if you aren’t creating global fields.

Be sure to customize the function names if you are copy and pasting from this article. Specifically, change the "myprefix" text to be customized to your site.

Store the Custom Field Data

What good is creating custom fields if our data is never saved anywhere? Let’s be sure we save our data by hooking into Give when the the donation payment is added to the database using the give_insert_payment action. This action allows us to add data to the payment’s post meta so it’s saved to the database and we can then display it the payment page in wp-admin. Here’s what the code looks like:

Store the Custom Field Data


/**
 * Add Field to Payment Meta
 *
 * Store the custom field data  meta.
 *
 * @param $payment_id
 * @param $payment_data
 *
 * @return mixed
 */
function myprefix123_give_donations_save_custom_fields( $payment_id, $payment_data ) {
	if ( isset( $_POST['give_referral'] ) ) {
		$message = implode( "\n", array_map( 'sanitize_text_field', explode( "\n", $_POST['give_referral'] ) ) );
		give_update_meta( $payment_id, 'give_referral', $message );
	}
}

add_action( 'give_insert_payment', 'myprefix123_give_donations_save_custom_fields', 10, 2 );

Display Custom Field Data in Payment Details

Let’s make sure that our custom field data is displayed when we view a payment now that our data is being saved properly when a donation is made. This is as simple as hooking into our the payment details page at the appropriate place where we want to display data. For this example we will use the give_view_order_details_billing_before action:

Show Data in Donation Details for Admins


/**
 * Show Data in Payment Details
 *
 * Show the custom field(s) on the payment details page in wp-admin within its own metabox.
 *
 * @param int $payment_id
 */
function give_myprefix_donation_details( $payment_id ) {

	// Bounce out if no data for this transaction.
	$give_referral = give_get_meta( $payment_id, 'give_referral', true );
	if ( $give_referral ) : ?>
        <div class="referral-data postbox">
            <h3 class="hndle"><?php _e( 'Referral Information', 'give' ); ?></h3>
            <div class="inside">
				<?php echo wpautop( $give_referral ); ?>
            </div>
        </div>
	<?php endif;
}

add_action( 'give_view_donation_details_billing_after', 'give_myprefix_donation_details', 10, 2 );
A new custom metabox called "Referral Information" appears below the "Billing Address" fields in the donation details within wp-admin.
A new custom metabox called “Referral Information” appears below the “Billing Address” fields in the donation details within wp-admin.

Above is an example of how you can customize the custom field data on your transaction details pages. You can output them in a list in the sidebar, or simply within the Donor’s details as we have here.

All the Code Together

This example uses the scenario where a user would like to collect referral information from the user via a custom textarea. The textarea is added to a specific form, validated, saved to the database, and then displayed in transaction details. Use this code as reference within your development. Here’s all the code that makes that work:

Full Example: Adding a Custom "Referral" Textarea to a Specific Form by ID



/**
 * Add Custom Donation Form Fields
 *
 * @param $form_id
 */
function give_myprefix_custom_form_fields( $form_id ) {
	// Only display for forms with the IDs "754" and "578";
	// Remove "If" statement to display on all forms
	// For a single form, use this instead:
	// if ( $form_id == 754) {
	$forms = array( 754, 578 ); ?>
    <div id="give-referral-wrap">
        <label class="give-label" for="give-referral"><?php _e( 'How did you hear about GDI?:', 'give' ); ?> <span
                    class="give-tooltip icon icon-question"
                    data-tooltip="<?php _e( 'Please take a second to tell us how you first heard about Girl Develop It.', 'give' ) ?>"></span>
        </label>
        <textarea class="give-textarea" name="give_referral" id="give-referral"></textarea>
    </div>
	<?php
// endif;
}

add_action( 'give_after_donation_levels', 'give_myprefix_custom_form_fields', 10, 1 );

/**
 * Validate Custom Field
 *
 * Check for errors without custom fields
 *
 * @param $valid_data
 * @param $data
 *
 * @return mixed
 */
function give_myprefix_validate_custom_fields( $valid_data, $data ) {
	// Only validate the form with the IDs "754" and "578";
	// Remove "If" statement to display on all forms
	// For a single form, use this instead:
	// if ( $form_id == 754) {
	$forms = array( 754, 578 );
//	if ( in_array( $form_id, $forms ) ) {
	$required_fields['give_referral'] = array(
		'error_id'      => 'invalid_give_referral',
		'error_message' => __( 'Please tell us how you heard about Girl Develop It.', 'give' ),
	);

//	}

	return $required_fields;
}

add_filter( 'give_donation_form_required_fields', 'give_myprefix_validate_custom_fields', 10, 2 );

/**
 * Add Field to Payment Meta
 *
 * Store the custom field data  meta.
 *
 * @param $payment_id
 * @param $payment_data
 *
 * @return mixed
 */
function myprefix123_give_donations_save_custom_fields( $payment_id, $payment_data ) {
	if ( isset( $_POST['give_referral'] ) ) {
		$message = implode( "\n", array_map( 'sanitize_text_field', explode( "\n", $_POST['give_referral'] ) ) );
		give_update_meta( $payment_id, 'give_referral', $message );
	}
}

add_action( 'give_insert_payment', 'myprefix123_give_donations_save_custom_fields', 10, 2 );

/**
 * Show Data in Payment Details
 *
 * Show the custom field(s) on the payment details page in wp-admin within its own metabox.
 *
 * @param int $payment_id
 */
function give_myprefix_donation_details( $payment_id ) {

	// Bounce out if no data for this transaction.
	$give_referral = give_get_meta( $payment_id, 'give_referral', true );
	if ( $give_referral ) : ?>
        <div class="referral-data postbox">
            <h3 class="hndle"><?php _e( 'Referral Information', 'give' ); ?></h3>
            <div class="inside">
				<?php echo wpautop( $give_referral ); ?>
            </div>
        </div>
	<?php endif;
}

add_action( 'give_view_donation_details_billing_after', 'give_myprefix_donation_details', 10, 2 );

An Additional Plugin Example

We have provided an example plugin which demonstrates how to add custom fields if you’re looking for a complete example. There’s also a number of other valuable snippets in that repo. We encourage you to check it out.

Take it a Step Further

Often you want the custom fields you create to be included within the various notification emails Give sends out. Let’s expand upon the functionality found in this one and learn how to add custom email tags to Give.