CiviMember - Online Contribution Page Wizard Modifications (civicrm/contribute/transact)

This issue covers form / page rendering and processing tasks in the online contribution page "wizard" which are triggered WHEN the CiviMember component is enabled AND an active MembershipBlock is linked to the current contribution page (civicrm_membership_block.entity_table = 'civicrm_contribution_page' AND entity_id = civicrm_contribution_page.id AND is_active = 1).

1. Render Membership Block in Main Contribution Page (Contribute/Form/Main...)
1.1 Add MembershipBlock elements to Main Contribution Page [new buildMembershipBlock() function called by buildQuickForm() ]. Membership block is rendered above Amounts Block. Block elements are:

• Title and Text: Default is to use new_title, new_text from membership_block. If a membershipID (mid=N) is defined when the page is invoked, we're doing a "renewal" - so use renew_title and renew_text. TPL layout for title and text should use same HTML/style as premiums block.

• Membership Type form element (membership_type_id):
  IF membership_block.membership_types has only one value, membership_type_id is a hidden field.
  IF multiple values, render radio buttons for membership_type_id IN (membership_block.membership_types). Radio button labels are composed of:

• membership_type.name + membership_type.description
• IF membership_block.display_min_fee = 1 then also include membership_type.minimum_fee in parentheses
• IF membership_block.membership_type_default - then that radio button element is checked.
• IF is_required is FALSE, then include additional radio button element for "No thank you" choice.

1.2 Add validation rule to the form builder:
IF BOTH amount_block_is_active AND membership_block.is_active are FALSE, then the page configuration is not valid and rather than rendering the page we display a status (error) message:
"The requested online contribution page is missing a required Contribution Amount section or Membership section. Please check with the site administrator for assistance."

1.3 IF contribution_page.amount_block_is_active is FALSE - do not include the amount block.

2. Validate Main Contribution Page

• If membership_block is active for this page AND membership_block.is_required (TRUE) then make sure a membership_type_id is being submitted (either the user has checked a radio button, or for the "single membership type case" - we have a membership_type_id passed from the hidden field). Validation error - "Please select a membership type."

• If amount_block_is_active AND is_separate_payment is FALSE, then validate that contribution amount is GTE selected membership_type.minimum_fee. This is similar to existing validation for selected premium. Validation message = 'The membership you have selected requires a minimum contribution of $minimum_fee.' (If amount_block is suppressed, then we automatically set contribution amount = membership_type.minimum_fee, so no amount validation is required in this case.)

3. Confirm Contribution
Confirm page should show "selected" (or "forced") membership info as well as contribution amount(s) to be charged. For cases where both a contribution amount is entered/selected AND a membership_type is specified, we use the membership_block.is_separate_payment property to determine whether the contribution amount is handled separately from the membership fee (see Process Contribution below).

If $50 contrib amt entered AND membership w/ $25 fee selected, do one transaction for $50
separate_payment T/F If amount_block NOT active AND membership w/ $25 fee selected, do one transaction for $25

3.1 If membership_block.is_active AND a membership_type_id has been posted, include a Membership confirmation display block on this page - above the Contribution Amount block.

• Block title uses new or renew_title as in Main.php. If these are null, default is "Membership Information".
• Display membership_type.name + description in the block.

NOTE: We display this info for both the single membership type case (i.e. where the user hasn't explicitly selected a radio button on the prior page), and the case where they've selected from a set of membership types. We do NOT display this block if they're said "No thank you" (same logic as confirmation for Premiums block).

3.2 Contribution amount block is always included on this page (even if amount_block_is_active is FALSE) - users need to see the amount of the transaction they're about to confirm. This block displays 1 or 2 transactions depending on separate transaction case (as above). If two transactions, should also show a Total Contribution line.

EXAMPLE 1: separate_transaction IS TRUE, with a $50 contribution entered AND a $25 membership_type selected

Contribution Amount
=========================
Gold Membership $25.00
Contribution $50.00
--------------------------------------------
Total $75.00

EXAMPLE 2: separate_transaction IS FALSE, with a $50 contribution entered AND a $25 membership_type selected

Contribution Amount
=========================
$50.00

4. Process Contribution
Modify code which invokes actual payment to conditionally generate TWO transactions (and hence two civicrm_contribution records) IF is_separate_payment is TRUE AND user has entered a contribution amount AND selected a membership. For the TWO transaction case, process the membership related transaction first, and make sure post process is sufficiently granular to give an appropriate error message if one of the transaction fails.

Case 1: separate_payment is TRUE; membership w/ $25 fee selected; $50 contrib amount entered.
Processing: Generate two transactions

• $25 for membership (contribution_type = membership_type.contribution_type_id)
• $50 for additional contribution (contribution_type = contribution_page.contribution_type_id)
• Grand total of transactions = $75.

Case 2: separate_payment is FALSE; membership w/ $25 fee selected; $50 contrib amount entered.
Processing: Generate one transaction

• $50 contribution (contribution_type = contribution_page.contribution_type_id)

Case 3: amount_block_is_active is FALSE; membership w/ $25 fee selected.
Processing: Generate one transaction

• $25 for membership (contribution_type = membership_type.contribution_type_id)

On success of a contribution which includes (or is) a membership payment, the following additional post-process steps are required:
4.1 One or two payments invoked. Resulting civicrm_contribution records should always use the contribution_type_id as shown above.
4.2 A civicrm_membership record must be created (or updated for renewal case).

• Membership properties for start_date, end_date, and calculated status are set based on membership_type data.
• join_date = start_date for inserts (not modified for renewal/updates).
• source = civicrm_contribution_page.name.
  4.3 A civicrm_membership_payment record must be created

5. Thank-you Page and Receipt
A membership display block is added to Thank-you page (same as Confirm page) and the email Receipt. Contribution amount(s) display is handled as in Confirm page.