Feature: add receipt api for fields

[jonwaldstein]

Resolves: GIVE-180

Description

Preface

For fields that either don't store their value in meta (or at all), use a custom scope, or the field attributes just does not correlate to what should be displayed on the confirmation page - there is currently no way to modify the label & value.

At first I was going to simply add an action like givewp_donation_confirmation_receipt (which we still can) but then realized how removed from context the action is as it relates to field data. For example, you will often need to go through the form schema to find the field to use field attributes/settings. Where as giving fields a first-class api has the benefit of staying in context with the rest of the field settings/schema and likely will reduce logic & overhead.

The solution

This gives fields a way to optionally & programmatically display their label/value in the confirmation page. Currently the receiptValue(Closure $value) api is a simple closure that (in the context of a donation form) will pass the $field and $donation model. I thought about adding a string option like scopes do but thought this would be the simpler way to go for now (since I also added filters).

For example:

$field = Select::make(FundField::FUND_ID)
->tap(function ($field) use ($block) {
    $this->setFieldOptions($field, $block);
})->scope(function (Select $field, $value, Donation $donation) {
    if (!empty($value)) {
        give(FundsRevenueRepository::class)->updateDonationFund($donation->id, $value);
    }
})
->showInReceipt()
->receiptLabel(__('Fund', 'give-funds'))
->receiptValue(function (Select $field, Donation $donation) {
    $fund = give(Funds::class)->getByDonationId($donation->id);
    if (!$fund) {
        return null;
    }

    return $fund->getTitle();
});

I also added a couple filters so folks could modify the values if need be:

• apply_filters('givewp_donation_confirmation_page_field_value_for_{$fieldName}', $value, $field, $donation)
• apply_filters('givewp_donation_confirmation_page_field_label_for_{$fieldName}', $value, $field, $donation)

These would be most useful for customers using add-ons that add their own receipt labels/values and might want to modify that (maybe for language, syntax, or something else). You could also use these filters instead of the fields api if need be - either way it's an easy win.

Affects

• The donation confirmation page

Visuals

Api in action! ("Fund")

Testing Instructions

• Add a field programmatically to the form
• use the new api for your receipt values

add_action('givewp_donation_form_schema', static function (DonationForm $form) {
    $field = Text::make('custom_text_field_example')
        ->showInAdmin()
        ->showInReceipt()
        ->scope('my_custom_scope_stored_somewhere_fancy')
        ->label('Whats your favorite color?')
        ->receiptLabel('Your favorite color is:')
        ->receiptValue(function (Text $field, Donation $donation) {
            // here you could do something fancy like get the value from a custom table
            // or derive from your field, etc.
            return "Blue!";
        });

    $form->insertAfter('email', $field);
});

Or with filters:

add_filter('givewp_donation_confirmation_page_field_label_for_custom_text_field_example', static function ($label, $field, $donation) {
    return 'Your new favorite color is:';
}, 10, 3);

add_filter('givewp_donation_confirmation_page_field_value_for_custom_text_field_example', static function ($label, $field, $donation) {
    return 'Blue';
}, 10, 3);

add_action('givewp_donation_form_schema', static function (DonationForm $form) {
    $field = Text::make('custom_text_field_example')
        ->showInAdmin()
        ->showInReceipt()
        ->scope('my_custom_scope_stored_somewhere_fancy')
        ->label('Whats your favorite color?');

    $form->insertAfter('email', $field);
});

Pre-review Checklist

• Acceptance criteria satisfied and marked in related issue
• Relevant @unreleased tags included in DocBlocks
• Includes unit tests
• Reviewed by the designer (if follows a design)
• Self Review of code and UX completed

[rickalday]

Passed manual QA tests.