Address Sharing for Contacts: replace Use Household Address with the ability to share addresses between any contact types

Summary
========
CiviCRM currently allows Individual contacts to "Use a Household Address". However, the implementation for this is limited to Individual => Household. Users want to be able to allow address sharing between a variety of contact types:

• Individual shares an address with another individual (spouses / relatives without using a household record)
• Individual shares an address with their Employer (organization)
  ...

When a contact shares an address with another contact, the shared address is replicated as a separate read-only copy in the address table and linked to the "master address" using a new key in the address table (master_id). Although this model means that duplicate data is stored, it avoids adding significant complications to search and display interfaces.

Implementation
============
1. Schema changes

• Add civicrm_address.master_id, INT, FK to civicrm_address.id ON DELETE SET NULL
  (we don't want to automatically delete a linked address copy when it's master is deleted, but simply make it "independent and editable" by setting the master_id = NULL)

• Drop civicrm_contact.mail_to_household_id

2. Contact editing
2.1 Replace "Use Household Address" field (checkbox and autocomplete widget) with "Share Address With" field pair (checkbox + select or create contact widget).

• This option should be available on all address blocks (not just Primary / 1st address block as currently).

• Address input fields for the current block are hidden when the "Share..." checkbox is selected (as currently.

• When you select a contact display it's address below the widget as radio options else give message for no address found.

EXAMPLE: Foobar Corp. has a primary address entered for the 'Main' office and 2 branch office addresses. When adding / editing Jane Doe who is an employee of Foobar Corp. and works at the San Jose branch, user needs to be able to select that address.

• Implement a HOOK which developers can use to filter the result set for this autocomplete widget.

• Address data should be displayed as user scrolls the results listing (as currently).*

• If user unchecks the "Shared with... " field, display the field values from the address copy in the form fields (same as we do now).

• Add a new reserved profile "Shared Address" with following address fields:

• street address
• city
• postal code
• state
• country

Once CRM-6934 is implemented we should be able to pass this gid along with standard new contact profiles so that user can create contact with address.

2.2 When editing an address block - check if other contacts are sharing this 'master' address. If so, add status message at the top of the address block: "This address is shared with $count contact records. Modifying this address will automatically update the shared address for these contacts."

• All updates on "master" address fields (contact edit and profile) need to update any address copy rows (e.g. check for address rows where master_id = this id, and update if found).

• Deleting a master address via clicking "Delete Address" from address block or by emptying the fields:
  • During postProcess, retrieve the contact ID's and display names of contacts who have addresses linked to this master address. Add the list of contacts to the status message which appears after the contact record is saved:
    "The following contact(s) have address records which were shared with the address you removed from this contact. These address records are no longer shared - but they have not been removed or altered."
    Mr. Dan Jones
    Ms. Sarah Smith

• • The master_id in any copies is set NULL (this is done automatically via FK).

2.3. Deleting a contact with a master (shared) address

• Add the following to the Delete Contact confirmation status message (check for addresses where master_id IN one of this contact's address id's):
  "This contact has an address record which is shared with other contacts. Shared addresses will not be removed or altered but will no longer be shared."

• Delete contact PostProcess:
  • Retrieve the contact ID's and display names of contacts who have addresses linked to this master address. Add the list of contacts to the status message which appears after the contact record is saved:
    "The following contact(s) have address records which were shared with the address you removed from this contact. These address records are no longer shared - but they have not been removed or altered."
    Mr. Dan Jones
    Ms. Sarah Smith

• • The master_id in any copies is set NULL (this is done automatically via FK).

2.4 We should create following relationships only if Individual contact type has shared address. Ignore creation of relationships for other contact types.

• If shared address is of Organization, create "Employee Of" relationship
• If shared address is of Household, create "Household Member of" relationship

3. Contact summary
First line of shared addresses (copies) should display: "Shared with $contact.display_name"
(display name is a link to view the contact record associated with the master address)
Note: Contact has multiple shared address then we should have above behavior for each address.

4. Export
address.master_id and display name of contact that address is shared with should be exportable and included in primary contact export. Column headers:

• Master Address ID
• Master Address Belongs To

5. Upgrades
Upgrade will need to handle existing "Use Household Address" cases in the DB and migrate them to the new sharing model. For each individual contact with contact.mail_to_household_id NOT NULL:

• retrieve the address.id of the primary address of the contact referenced in contact,mail_to_household_id
• write this value to the new address.master_id column of the primary address of that contact.
• Add reserved profile to upgrade script.