Change event registration selections for an existing participant (back-office)

-------------
Summary
-------------
Back-office staff may:

• Update event registration selections for an existing participant.
• Record a payment or a refund if the participant has already paid AND the new fee total is different the original payment
• The contribution amount will adjusted to the new amount owing, as appropriate.
• If amount owing is greater than amount paid, contribution and participant status will be set to "Partially paid". User can over-ride participant status on the form.
• If amount owing is less than amount paid, contribution and participant status will be set to "Pending refund". User can over-ride participant status on the form.

---------------------
Implementation
----------------------
1. Add new activity type - Change Registration. Reserved=True, Component=CiviEvent, Description="Changes to an existing event registration."

• add to civicrm_data.tpl
• insert for upgrades

–
2. Edit Participant / View Participant forms

• Add a button below the line-item table: "Change Selections"
  (see screenshot EditRegistration.png).
• Button click redirects to a new Change Registration Selections form, passing contact ID and participant ID in the URL.

–
3. Change Registration Selections form
3.1 New form class (see screenshot attached - ChangeRegistrationSelections.png)

• Read-only fields for participant display name, event title and event date
• Read-only display of existing line-items and Event Total amount
• Embeds the existing price set form snippet
• Below price set form, 3 additional read-only fields; Total Fees (dynamically calculated based on price set form selections); Total Paid (same as Event Fees above); Balance (=Total Fees - Total Paid, may be negative in refund case)
• Participant Status field (default to existing status)
• Participant Confirmation and Notes fields
• Submit buttons are 'Save' and 'Save and Record Payment'

Client Side form behaviors (jQuery)
------------------------------------------------

• If calculated Balance is positive, set Participant Status to 'Partially paid' (user MAY override this and change it to something else later)
• If calculated Balance is negative, set Participant Status to 'Pending refund' (user MAY override this and change it to something else later)

• When user clicks "Save" if the Balance is positive AND the participant status != 'Partially paid', put up a jScript confirm dialog:
  "Balance is owing for the updated selections. Expected participant status is 'Partially paid'. Are you sure you want to set the participant status to $statusLabel? Click OK to continue, Cancel to change your entries."

• When user clicks "Save" if the Balance is negative AND the participant status != 'Pending refund', put up a jScript confirm dialog:
  "Balance is overpaid for the updated selections. Expected participant status is 'Pending refund'. Are you sure you want to set the participant status to $statusLabel? Click OK to continue, Cancel to change your entries."

3.2 Pre process

• If related participant (contact) does not have a valid email address, display status re: can not send a confirmation and hide the Send Confirmation and From fields (same as existing event registration form).

3.3 Post Process

• Update and insert line_item rows as needed. If an existing line_item is no longer selected, set QTY and LINE_TOTAL to 0 rather than deleting the line_item

• Update and insert financial_item rows linked to line_items as needed. Financial_item changes need to handled as an adjustment. Refer to this data flow for amount adjustment procedure: http://wiki.civicrm.org/confluence/display/CRM/CiviAccounts+4.3+Data+Flow#CiviAccounts4.3DataFlow-Changecontributionamount%28quickconfig/singleline_item%29

• If new fee total is != to total paid:

• Insert financial_trxn and entity_financial_trxn for adjustment to total contribution amount.
• Update contribution amount to new Total Fee(s) amount.
• Update contribution status to 'Partially paid' if Balance is positive. Update to 'Pending refund' if Balance is negative.

• If [x] Send Confirmation is checked - trigger the existing Event Confirmation (offline) message template. User is responsible for explaining that this is a 'change notification' in their confirmation message.

• Create new activity (type = Change Registration). Data pattern similar to Contribution activity:
  Source Contact = logged in user's contact
  Target Contact = payee contact
  Subject = "Registration selections changed for $eventTitle - $eventDate"

• If 'Save and Record Payment' button is clicked, redirect to Financial Transaction form after save, pass contact ID and participant ID.

• Cancel on form should return to last form or page that the user was on. Successful submit should return to contact's Event tab.

–
4. Tests
4.1 Extend existing Event (participant) and Financial BAO tests to cover changing registration selections for a participant record. Check for expected participant and contribution status changes as well as expected new activity record.

4.2 Extend existing Event (participant) and Financial BAO tests to cover recording 'refund' for a 'Pending refund' participant record. Check for expected participant and contribution status changes as well as expected new activity record.

4.3 Create web-tests which covers the change selections flow (no fee change, balance owed, and refund due cases).