Issue/509

[kevinwhoffman]

Description

Improves receipt-viewing experience discussed in #509 with the following changes:

• Receipts now display on Donation History page instead of Donation Confirmation page, allowing for a more predictable UI when clicking into an individual receipt.
• Whether user sees full donation history or individual receipt depends on presence of payment_key query arg in URL.
• Link back to all donations is provided below receipt.
• [give_receipt] shortcode has two new attributes:
  • payment_status determines whether status row within receipt is displayed. Default false.
  • status_notice determines whether notice above receipt is displayed. Default true.
• give_receipt_status_notice filter allows users to filter the notice.

How Has This Been Tested?

• Created a donation with each possible status.
• Confirmed each status displays the relevant notice.
• Confirmed Donation Status row is hidden by default.
• Confirmed shortcode atts can override default behavior.
• Tested against non-English locales.

Screenshots (jpeg or gifs if applicable):

Types of changes

Resolves #509

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows has proper inline documentation.

Documentation Updates

@mathetos We will need to update https://givewp.com/documentation/core/shortcodes/give_receipt/ with the following changes:

• Clarify when receipt appears on Donation Confirmation page vs. Donation History page.
• Document new [give_receipt] shortcode attributes.
• Document new give_receipt_status_notice filter with examples.

New Filter: give_receipt_status_notice

/**
 * Filters payment status notice for receipts.
 *
 * By default, a success, warning, or error notice appears on the receipt
 * with payment status. This filter allows the HTML markup
 * and messaging for that notice to be customized.
 *
 * @since 1.7.0
 *
 * @param string $notice HTML markup for the default notice.
 * @param int    $id     Post ID where the notice is displayed.
 * @param string $status Payment status.
 * @param array  $meta   Array of meta data related to the payment.
 */
echo apply_filters( 'give_receipt_status_notice', give_output_error( $notice_message, false, $notice_type ), $id, $status, $meta );

Basic Example

Customize an error notice based on donation status.

function prefix_custom_failed_notice( $notice, $id, $status, $meta ) {
    if ( 'failed' === $status ) {
        return give_output_error( __( 'Whoops! Something went wrong.' ), false, 'failed' );
    }

    return $notice;
}
add_filter( 'give_receipt_status_notice', 'prefix_custom_failed_notice', 10, 4 );

Advanced Example

Personalize a success notice with the donor's first name. This is possible because we are passing $meta to the hooked function.

function prefix_personalized_success_notice( $notice, $id, $status, $meta ) {
    if ( 'publish' === $status ) {
        $first_name = $meta['user_info']['first_name'];
        $notice_message = sprintf( __( '%s, your generous donation is most appreciated!', 'text_domain' ), $first_name );

        return give_output_error( $notice_message, false, 'success' );
    }

    return $notice;
}
add_filter( 'give_receipt_status_notice', 'prefix_personalized_success_notice', 10, 4 );

[DevinWalker]

Love the examples! Thanks!

[mathetos]

@kevinwhoffman Looks really awesome. Only one nit-picky item, I think the filter should be called give_receipt_status_notice ... don't have plans for more receipt notices right now, but don't want to have the need and not have good filter name options.

[kevinwhoffman]

@mathetos I'm good with that, but I think we should be consistent and do the same for the shortcode attribute, which is currently named notice.

In summary, the new additions would be:

• New Filter - give_receipt_status_notice
• New shortcode att - payment_status (determines whether status is displayed within receipt)
  • I named it like this to match the other existing atts which you can toggle on/off.
• New shortcode att - status_notice (determines whether notice is displayed above receipt)

[mathetos]

@kevinwhoffman Ya, makes sense. Why are these checks failing?

[kevinwhoffman]

@mathetos I pushed those changes and edited my first comment in this PR so the documentation and examples will reflect the correct name usage.