feat(email): display any meta data with dynamic email tags

[kevinwhoffman]

Issue Overview

Users often want to display meta data within their emails, but a specific tag for that meta data may not exist. Since donor and donation meta data are stored in predictable locations, there should be a way for users to define what meta data they want to display through dynamic email tags.

Expected Behavior

Meta data that is collected should be displayable in emails.

Current Behavior

Displaying meta data currently requires a specific tag.

Possible Solution

Add two dynamic email tags capable of reading meta data based on the provided key. The tag would begin with either donation_ or donor_ depending on whether the meta data is stored alongside the donation or donor.

Examples:

• {donation_transaction_id}
• {donor_email}

Related Issues and/or PRs

impress-org/givewp-snippet-library#62

[ravinderk]

@DevinWalker @mathetos @kevinwhoffman

I kept in mind when I created the snippet that we cannot create email tags for all donation metadata and there must be an easy way which can handle by admin.

@kevinwhoffman I like the way you suggested tag named but all donation meta does not follow meta key name standard and we do not know which naming will be followed by the third-party addon.
for example: _give_current_url, _give_current_page_id

This logic is not only for core, but it is for all addon which will be created in future fo give.
That's why I kept it simple {meta_*}.

By revisiting the scope of dynamic email tag. I want to add following suggestion.

Donation : {meta_donation_{meta_key} {array_key|optional} }
Donor: {meta_donor_{meta_key} {array_key|optional} }
Form: {meta_form_{meta_key} {array_key|optional} }

Dynamic name details:
meta_key: meta key name in which you are storing data.
{array_key|optional} }: if meta key contains data in an array and you want to get specific data from that array. It will help to get metadata from donation, form, and donor even if it is an array.

For example:
{meta_donation__give_payment_transaction_id}
{meta_donation__give_payment_meta currency}*
{meta_form__give_price_option}
{meta_donor__give_stripe_customer_id}

_give_payment_meta deprecated in 2.0, I am using this only for example. You can get currency from _give_payment_currency meta key.

[kevinwhoffman]

@ravinderk You're much more familiar with the meta architecture than I am, so I trust your judgement on this.

How do you anticipate users knowing which tag to use? Will they be listed alongside the other tags when editing an email template, or will they have to know the meta_key from some other source? That list could get pretty long if we list out every key, but I also think users will need these tags spelled out for them in order to understand how to use them.

I suppose even if users don't grasp the feature on their own, it will at least give Support a quick solution for anyone with these kinds of requests.

[ravinderk]

@kevinwhoffman

How do you anticipate users knowing which tag to use? Will they be listed alongside the other tags when editing an email template, or will they have to know the meta_key from some other source? That list could get pretty long if we list out every key, but I also think users will need these tags spelled out for them in order to understand how to use them.

Agree with you. Output list will not be a good idea because the list will keep increasing. On this, we need @mathetos help. Maybe we can document it somewhere or boost an email to plugin users which will inform plugin about it. We can also document general email tag format on email message editor.

I suppose even if users don't grasp the feature on their own, it will at least give Support a quick solution for anyone with these kinds of requests.

This is the main purpose to develop it.

[kevinwhoffman]

I agree. A link at the bottom of the existing tags list could point to the documentation for these dynamic tags.

[mehul0810]

Slack Call Summary

Participants: @ravinderk @mehul0810
Topic: Discussion about meta tag not working for donors
Result: Showed Ravinder how donor meta email tags are not working and provide a couple of email meta tags which are not working due to blank metadata for donors. {meta_donor__give_donor_first_name} and {meta_donor__give_donor_last_name}

[ravinderk]

Slack Call Summary
Participants: @ravinderk @mehul0810
Topic: PR testing
Result: Showed Mehul that all type of meta working fine ( also with FFM)

[mathetos]

I need to review in more detail, but at first read I think the tags should be prefixed only with donor_ or donation_ like discussed in Slack.

But I'll review in more detail in a bit.

[ravinderk]

@mathetos donor_, donation_ and form_ is a common prefix, so it can conflict with another tag.
That why created prefix meta_donor_, meta_donation_ and meta_form_ which also reflect the purpose of this tag means show metadata.

[mathetos]

@ravinderk That makes sense, I see what you mean and understand.

I agree with Kevin that adding a link to full documentation would be good. Here's the wording I'd suggest for that sentence and link:

See our documentation for examples of how to use custom meta email tags to output additional donor or donation information in your Give emails.

[ravinderk]

@mathetos Text added.

[mathetos]

@ravinderk A couple things on that:

1. "See our documentation..." should be at the END of the list. It will be the least often used.
2. There should be a line break so that "Available template tags" is on it's own line, separated from the "The email that is sent..." by a blank line.

[ravinderk]

@mathetos Changes done.

[mathetos]

@ravinderk I tested this fully today. Everything seems to work as intended except for the donor meta. I tried with all the variations of the following:

• {meta_donor__give_stripe_customer_id}
• {meta_donor__give_date_created} or _give_donor_date_created etc...

Note that {meta_donor__give_donor_last_name} and first_name works, but those are already working with existing email tags, it's basically all Donor related tags that are NOT already existing email tags.

Also note that meta_donation_ and meta_form_ tags are working just as intended.

I want to fully document this new feature but it need to be able to see it correctly. If you test and have it working then let me know what I'm missing. Otherwise, maybe we should re-open this until those tags work as intended.

[ravinderk]

@mathetos

1. can confirm that _give_stripe_customer_id metadata creates before email send?
2. _give_date_created is not donor meta but it seems you want date_created which is part of donor table. I added support for it. You will data directly from donor table if not find in donor meta table. {meta_donor_id}, {meta_purchase_count} etc.
   4822659...ee827d8

[mehul0810]

@mathetos @ravinderk
I've tested this issue and both the email tags ( i.e. {meta_donor__give_stripe_customer_id} and {meta_donor_date_created} ) are working fine. For email tag {meta_donor__give_stripe_customer_id} there is an issue when the test mode is enabled. You can check the condition in give_stripe_get_customer_key fn.

[mathetos]

Thanks for testing @mehul0810 -- I pulled the latest 2.1 and {meta_donor_date_created} is working as intended now.

Regarding {meta_donor__give_stripe_customer_id} I looked at the give_stripe_get_customer_key function which says basically to append _test to the end, I did that like so: {meta_donor__give_stripe_customer_id_test} and all worked well as well.

Thanks! I'll close this out again.