Discussion ticket for handling multivalued tokens in pdfs/emails
In particular related to:
-
https://github.com/civicrm/civicrm-core/pull/12012
- and its rebased version https://github.com/civicrm/civicrm-core/pull/16200
- https://github.com/civicrm/civicrm-core/pull/16208
There are a number of ways to deal with multivalued fields when you need to produce scalar output based on the field.
For example:
- Take the "first" one.
- This has the disadvantage that "first" doesn't really mean anything, especially if the order is not guaranteed to be the same each time.
- Take the "last" one.
- Ditto.
- Combine them separated by commas.
- This has the disadvantage that it may not make any sense or might look silly. Consider something like the "With Contact" on an activity. Suppose there are 3. Suppose you want to include the primary phone of the contact. Your pdf might look like this. It's not terrible, but now think about adding in address too.
- With Contact: John Smith, Mary Brown, Indiana Jones
- Phone: 555-123-2222, , 555-383-8383
- And it's not clear to me that it can guarantee that the phone values are in the same order as the names when the tokens are separate.
- This has the disadvantage that it may not make any sense or might look silly. Consider something like the "With Contact" on an activity. Suppose there are 3. Suppose you want to include the primary phone of the contact. Your pdf might look like this. It's not terrible, but now think about adding in address too.
- Do as in https://github.com/civicrm/civicrm-core/pull/12012, where you give the template designer the option to specify a numeric suffix on the token, e.g. {activity.target_2_display_name}. The way it's implemented there has some limitations:
- The order is still arbitrary - what does "2" actually mean?
- The template designer doesn't know max(N), so they can't easily do something like concatenate all of them if they want to.
- Provide some shorthand tokens for some common uses, e.g.
- {activity.target_1_phone} means arbitrarily take the first one.
- {activity.target_COMBINE_phone} means combine all with commas.
- {activity.target_ALL_phone} means give an array and I'll do some smarty-based looping in my template to get what I want.
Further, there are some situations where you might not want some recipients to see some of the other values. An example might be activity.case_id as in 16208. There maybe it makes sense to have a token that means "concatenate all the cases where the recipient has a role, and leave out the others". A similar one might apply for activity.target_display_name, where it might mean "concatenate all the with contact display names for activities where the recipient is one of the activity_contacts.
A related note that's just food for thought: In my other life, I always try to set up 2 fields when somebody asks for something multivalued. For example "services performed". Somebody might come to you asking for a couple of the different types of service you offer. You can designate one as the primary service, which is a single-valued field, which then makes reporting work because you don't run into double-counting, and then have a secondary services field that is multi-valued, which you don't use for reporting, and in emails/pdfs you can concatenate it without it being arbitrary because you would also output the primary which is single-valued. That may not be useful right now, but this is a discussion ticket.