Migrate "In Honor of" to Soft Credits

=======
Summary
=======
In Honor of / In Memory of are currently handled as a special type of property for contributions. They are better modeled as types of soft credits. The migration tasks are:

• Modify online contribution page configuration to allow admin to select soft credit type(s) and select an "honoree (soft credit) profile" to use in the honoree block. The honoree profile can be either Individual, Organization or Household (honoree contact can be any one of those types).
• Remove honoree section from back-office contribution edit and view forms
• Upgrades:

• Convert honorees in contribution table to soft credits
• Remove honor_contact_id and honor_type_id from contribution table
• Insert new reserved "Honoree Individual" profile
• Set default honoree profile and default soft-credit types for any contribution page that has an active honoree block

• Ensure that developers can implement a hook to set a relationship between the soft credit contact and the donor

============
Implementation
============
1. New reserved profile: "Honoree Individual"

• Add a new profile to the metadata for new installs and upgrades
  Title: Honoree Individual
  Name: honoree_individual
  Reserved: TRUE
  Type: Individual,Contact
• Profile Fields
  Individual Prefix - optional
  First Name - required
  Last Name - required
  Email Address (primary) - optional

2. Online Contribution Page Configuration
Soft credit (honoree) profile and meta-data for a contribution page is configured via a row in the uf_join table. We will distinguish this profile (ufjoin row) from top/bottom profiles using a different constant in uf_join.module column. Existing profile rows have module=CiviContribute. Use module=soft_credit for soft credit profiles. We will store related meta-data for the honoree block in a new ufjoin column (module_data).

2.1 Schema changes

• Add column to uf_join table to store data / attributes associated with a uf_join 'module'. This will be used to store all meta-data associated with the soft_credit (honoree) configuration in a json-serialized array:
• 'soft_credit_types' - active soft credit type option values
• 'honoree_title'
• 'honoree_text'

uf_join.module_data VARCHAR 255 'Json serialized array of data used by the ufjoin.module keyed by module.'

EXAMPLE:
jsonencode(array(
  'soft_credit' => array(
    'soft_credit_types' => array(1,5,6)
    'honoree_title' => 'Name someone cool',
    'honoree_text' => 'give us money in their name'
  )
));

• Remove honor_block_title and honor_block_text from civicrm_contribution_page table. We will store that data in uf_join.module_data.

NOTE: going forward the module_data column can be used to store data attributes for other "related contact" flows (e.g. relationship types, etc.).

• Remove honoree_block_is_active from civicrm_contribution_page table. We can use uf_join.is_active to flag when there is a soft credit/honoree block included on the contribution page (WHERE module = 'soft_credit').

2.2 Title and Settings form changes

• Add form field below honor_block_text to select the soft credit types to be shown on the contribution page. If no values are selected, default types s/b "In Honor of" and "In Memory" (this way the default behavior will render those 2 options as radio buttons on the contribution page so that the choices are the same as in 4.4)
  Field Label: Honoree Types
  Field Name: soft_credit_types
  HTML Type: asmMultiSelect
  Form Rule: At least one value must be selected if honor_block_is_active checkbox is checked

• Add "pencil" icon to the right of the multi-select field. On hover - "Click to edit available soft credit types.". Clicking pencil loads soft credit types option group listing page in a jquery dialog. See this CiviHR issue for implementation details: http://issues.civicrm.org/jira/browse/HR-221

• Add an instance of the new profile selector w/ inline preview, edit and create options to Title and Settings tab below soft_credit_types field (see CRM_Contribute_Form_ContributionPage_Custom::buildQuickForm for the addProfileSelector implementation).
  Field Label : Honoree Profile
  HTML Type: select
  Form Rule: Required IF honoree_block_is_active = TRUE

Filter Options: We want the user to be able to use any profile with Profile Type = Individual, Organization or Household. However, the profile needs to include the fields required to create a valid contact of that type (e.g. Individual profile must have email OR first+last name, Organization profile must have organization name, Household profile must have household name). The addProfileSelector method might need to be extended for this use case.

2.3 Post Process

• honoree_block_is_active set's ufjoin.is_active (WHERE module = 'soft_credit').
• Insert / update selected honor profile in uf_join table (module = 'soft_credit) and save soft_credit_types, honor_block_title and honor_block_text as Json-serialized array to ufjoin.module_data column.

NOTE: if honor_block_is_active is subsequently unchecked, retain the existing soft_credit uf_join row. The meta-data configuration (honor_title, honor_text, soft_credit_types) is retained in ufjoin.module_data, and can be shown / edited in those form fields if and when admin makes the honor block active again for that contribution page.

–
3. Online contribution pages
NOTE: The default contribution page configuration values (above) should result in a contribution page which looks the same as a 4.4 page with Honoree block active.

3.1 Form changes (Main)

• The enabled honoree_soft_credit type labels are rendered as radio buttons (replacing honor_type_id radio buttons)
• The enabled soft_credit profile replaces the 4 existing hard-coded fields (honor_prefix_id etc.)

Create a new generic class (CRM_Contact_Form_ProfileContact) and implement it to handle the generic preProcess, buildQuickForm and postProcess requirements. CRM_Contribute_Form_SoftCredit will handle only the tasks specific to the soft credit case (e.g. building fields for honoree_title, honoree_text, soft_credit_types) and then call the new generic class (CRM_Contact_Form_ProfileContact). CRM_Contact_Form_ProfileContact should not include any logic specific to the soft credit case. Review CRM_Contribute_Form_Contribution_OnBehalfOf as a second example to help in implementation of the generic class.

NOTE: We can look at migrating OnBehalf to use the generic class as a separate project.

On the template side, the new template for Soft Credit block (CRM_Contribute_Form_Contribution_SoftCredit) should ONLY handle soft-credit specific fields. It should use Dynamic.tpl to handle the profile fields (passing in a field prefix).

Add a region tag around the block:

{crmRegion name="contribution-soft-credit-block"}

…. code …

{/crmRegion}

3.2 Form changes (Confirm / Thankyou)
We need to replace the code which renders the honoree 'pane' on Confirm and Thank-you pages.

• Use selected soft credit type label as the pane 'header' text. (instead of using honoree_text here)
• Render the values from the honoree profile (read-only) in the honoree section as follows:

• Construct the honoree contact name from as we would display_name using available profile fields and render w/o label

• for individuals: prefix (optional) + first + last + suffix (optional)
• for organizations: org name
• for households: household name

• render all other profile fields as we do for other profiles on the confirm and thank-you pages (label: value)
  (See screenshots attached.)

3.3 Processing changes

• Creation of soft-credit contact is now driven by the soft-credit profile (ufjoin.module = "soft_credit"). Contact may be an individual, household or organization depending on the profile type.
• Soft credit (contribution_soft) of the selected soft_credit_type is created with contribution_soft.contact_id = the soft_credit contact.
• Remove code which populates contribution.honor_type_id and honor_contact_id

–
4. Back-office contribution form and Contribution tab

• Remove the Honoree Information pane and it's fields from this form (user will add Honorees in the soft credit pane).
• Remove the "Contributions made in honor of xyz" section of the Contributions tab (selector code and template section)

–
5. Upgrades
5.1 Schema and metadata changes as described above

5.2 Contributions
For each contribution with a non-null honor_contact_id

• create contribution_soft record with soft_credit_type_id = either In Honor of or In Memory (based on honor_type_id from contribution record)

5.3 Contribution pages
For each contribution_page with honor_block_is_active TRUE

• insert uf_join table entry with new Honoree Profile as uf_id; module = "soft_credit"; module_data = json array of soft_credit_type_id values for In Honor of and In Memory PLUS honor_title and honor_text; is_active = 1. (Need to do these inserts PRIOR to dropping the columns from contribution_page column )

–
6. "Gift" Membership changes (back-office membership form)
Currently when is_different_contribution_contact is checked on the the back-office membership form, we set contribution.honor_contact_id = the contact ID of the contact we are creating the membership for. Since honor_contact_id is being dropped, we need to modify the form elements and post-processing:

• replace honor_type_id with soft_credit_type_id (populated from soft_credit_types option_group)
• modify post process to create a contribution_soft record for the member contact (instead of writing that contact ID to contribution.honor_contact_id

The same changes are required for the Membership Renewal form (CRM_Member_Form_MembershipRenewal).

–
7. Remove "In Honor Of" field from Find Contributions / Advanced Search "Contributions" pane.

(NOTE: users will be able to search by "Honoree" using soft credit search features spec'd here: http://issues.civicrm.org/jira/browse/CRM-12467)

–
8. Remove "Honoree Email" and "Honoree Contact" from Contribution Details (Report/Form/Contribute/Detail.php) and "Contribution and Membership Details" (Report/Form/Member/ContributionDetail.php) reports.

(NOTE: users will be able to report on "Honoree" using soft credit type features spec'd here: http://issues.civicrm.org/jira/browse/CRM-13833)

–
9. Pledges
The soft credit schema does not support linking soft credits to pledges. In addition, the honoree-pledge functionality is not currently working in a useful manner. Back-office pledges do persist the honoree columns in the pledge table but they are NOT used to set default honoree values for subsequent payments on the pledge. Self-service (online) pledges aren't even saving the values. Rather than making schema changes to link soft credits to pledges, we will add logic to set soft credit defaults for pledge payments based on the most recent completed payment. This works for both self-service and back-office pledge flows. For self-service flows, if the donor selects a soft credit honoree while filling in the online contribution form - this will be stored in the 1st payment (contribution), and then we can default the same value if they use self-service page for subsequent payments. In the back-office, the staff person can fill in the soft credit honoree when recording the first payment - which again will default when they record subsequent payments.

• DROP honor_contact_id and honor_type_id from civicrm_pledge table

• Back-office pledge payments:
  Implement logic to set default soft_credit values for new contributions which are payments against a pledge IF the most recent completed contribution against that pledge has linked soft credit(s).

• Online contribution page:
  When user is making a contribution against an existing pledge (e.g. pledgeId=N is included in GET params), check most recent completed contribution against that pledge for existing linked contribution_soft row. If found, load honoree soft credit type / profile defaults IF the soft credit block is enabled on that contribution page. If > 1 soft credit against previous contribution, grab the first one (since we don't support multiple soft credits in the online contribution page form).

NOTE: Given that the honoree data in Pledge records was not being used to set defaults for pledge payments, AND given that the 4.5 code will set honoree soft credit defaults based on completed contributions, I think it's ok to drop those columns. The only 'edge case' that could cause problems is a pledge record that has non-null honoree columns AND doesn't have any completed pledge payments (i.e. completed contributions against the pledge). I think the "risk" is minimal.