CRM-4575 Greeting and Addressee improvements : customizable greeting for emails; customizable greeting and addressee for postal communications

Background
=========
The current solutions for including greetings in email and postal communications are limited / broken. There is a greeting_type field for contacts, but there is no token support for emails. If you export this field for mail-merge purposes, the variable "token" elements in the greeting type field are not converted to data values (e.g. export output is "Dear [first]", instead of "Dear Dana").

You can use contact tokens (e.g.

{contact.first_name} ) in email messages - but there is no way to specify different greeting patterns for specific recipients of the mailing. See this blog post for more details on the problem and suggested solution: http://civicrm.org/node/558

The same problems occur in specifying the 'addressee' line for mailing labels and / or exports for mail merges. There's no way to differentiate the address line contents for contacts which need to be addressed as a couple, or in some other distinct manner. (e.g. "Jane and George Jetson", vs. "Honorable Judge Roy Bean", vs. "Mr. Elroy Jetson")

Users have also suggested removing the specific "salutation" used in a given communication ("Dear", "Hi", "Greetings" ...) from the "greeting name". The new greeting "patterns" provided by default will still include salutations - the default Email and Postal Greetings will be "Dear {contact.first_name}

". However, the greeting options will be configurable - so sites can decide to remove the salutations and allow users to manually enter them in the message / document content.

Implementation
============
1. Schema Changes to civicrm_contact table:
Replace the existing greeting_type_id and custom_greeting columns with new pairs of columns for email greeting and postal greeting. A "_custom" column is needed for each attribute to allow for explicit values when tokens won't work (e.g. "Jane and George Jetson").

• Drop greeting_type_id
• Drop custom_greeting
• Add email_greeting_id, INT, implicit FK to civicrm_option_value, option_group = 'email_greeting'
• Add email_greeting_custom, VARCHAR(128)
• Add postal_greeting_id, INT, implicit FK to civicrm_option_value, option_group = 'postal_greeting'
• Add email_greeting_custom, VARCHAR(128)
• Add addressee_id, INT, implicit FK to civicrm_option_value, option_group = 'addressee'
• Add addressee_custom, VARCHAR(128)

2. Populate option groups and option values for default options (civicrm_data.tpl)
2.1 Add option groups for 'email_greeting' and 'postal_greeting'

2.2 Add option values for email_greeting and postal_greeting option groups. Replicate the 4 current options for 'greeting_type' option group. However, use our real token format instead of the pseudo-tokens used in the current entries. (This will allow us to evaluate the strings using our standard token eval functions.)

Default option for both groups for Individual contacts = "Dear

{contact.first_name}"

EXAMPLE of change to use "real" tokens in option_value.label:
Instead of "Dear [first]", use "Dear {contact.first_name}

"

We also need an option_value row for Household greetings, and probably should filter the options by contact type. We can use the 'filter' column to indicate which type of contact the option_value is used for.

For Households, option values for both groups are:
"Dear

{contact.household_name}" - default value
"Customized" - this one could be "shared" - i.e. filter is NULL

2.3 Add option_group and option_value rows for 'addressee'. Also use filter to differentiate options for different contact types:

For individual contacts:
"{contact.individual_prefix}{ } {contact.first_name}{ }{contact.middle_name}{ }{contact.last_name}{ }{contact.individual_suffix}" - default

For Household contacts:
"{contact.household_name}

"

For Org contacts:
"

{contact.organization_name}

"

For all contact types:
"Customized"

3. Contact edit form
Replace "Greeting" field with "Email Greeting", "Postal Greeting" (individual contacts only). "Addressee" fields should be available for all 3 contact types.

Text input field for "custom" string is displayed next to the <select> if "Customized" option is selected. If the "custom" field is empty, use jscript to write a default salutation into the field ("Dear"). If the user doesn't add any additional text to the field, then clear the default string ("Dear") so that we don't wind up with a custom greeting is only the default salutation (similar logic to what we currently do with Website URL). Also need a form rule for this - if a greeting type = Customized, then the custom greeting field must have a value.

For any non-custom option, display the evaluated output for this contact based on the selected option. This gives the user a clear view of what the actual greeting or addressee output will be for this contact based on their selection. (Same behavior for all 3 fields.)

EXAMPLE: If this contact's First Name is David, and I've selected "Dear

{contact.first_name}", display "Dear David" to the right of the <select> box.

4. Contact summary screen
Add greetings / addressee fields to the Comm Prefs section (display "evaluated strings" - e.g. "Dear David")

5. Token implementation
The following new tokens should be available for mailings, mailing labels, and ?? (where else do we support tokens?):
{contact.email_greeting} {contact.postal_greeting} {contact.addressee}

6. Address settings
6.1 Modify the default value for "mailing_format" field under Global Settings >> Address Settings >> Mailing Labels. First line is now {contact.addressee}

6.2 I don't think we need the individual_name_format field any more since contact.address handles the variations between different types of contacts (and the actual addressee line format is set at the contact level). (Let me know if you think we still need this setting for some other reason. Otherwise we should drop this column from civicrm_preference)

7. Export
Primary contact exports should include the following columns (they should also be available to select for mapped exports):
- Email Greeting
- Postal Greeting
- Addressee
If the contact has a one of the tokenized optioins, outputs should be the evaluated string (based on selected option for the contact). If the contact has a "Customized" value, then output the corresponding "custom" column value instead.

EXAMPLES:
Contact 1 : email_greeting_id = 1 ( "Dear {contact.first_name}

" ), Email Greeting exported = "Dear David"
Contact 2 : email_greeting_id = 4 ( "Customized" ). Email Greeting exported = value stored in email_greeting_custom

8. Import
All six fields should be importable.

If a Custom Email Greeting, Custom Postal Greeting or Custom Addressee is mapped, and no "Greeting / Addressee Type ID" is provided, then automatically set the type id = Customized (get value). Throw an error if Email or Postal Greeting Type, or Addressee Type != Customized AND a Custom Greeting column is mapped and has a value for a given row. ("Please specify Customized Email Greeting type if a custom greeting value is being provided for this contact.")

9. Upgrade Notes
Email and Postal greeting values should be set based on the current value of greeting_type_id for each contact . If a custom_greeting has been set for a contact, copy that into BOTH the new email_greeting_custom and postal_greeting_custom fields and set _id to Customized value.

Set civicrm_contact.addressee_id to default value for the given contact type.

Check for

{contact.contact_name}

in civicrm_preference.mailing_format. If found, replace with

{contact.addressee}

.

NOTE: We'll need to warn folks if they've modified the individual_name_format string from the default value - since the post-upgrade behavior will be different for them (and they'll need to edit the default option_value for Individual 'addressee').