Making the manage instalments screen more flexible, where the user can now add a membership line item, even when all the instalments within the payment plan are completed (paid).
Before
Currently, the ability to add new membership line item (or even a normal line item) is not supported in Membershipextras when all the the instalments (contribution) within the payment plan are completed (paid), and an error toast message is shown when the user tries to do so.
(the error toast message appears in the background currently, but that is a separate and known UI problem)
After
Instead of showing the error toast message mentioned in the "before" section above, we now present two options to the user, the first is to create the membership without charging the user for it in the current period:
With this option, the following happen:
1- New Membership with the selected type and dates will be created
2- New membership subscription line item will be created on the payment plan, which the user can see inside the manage instalments screen, the amount of that line item is 0, and will automatically renew with the rest of the payment plan (unless the user ticks the auto renew checkbox off when adding the line item). though for the autorenewal to pick the price of the membership correctly at autorenewal , the Membershipextras "Use latest price when auto renew membership" setting should be enabled:
The second option is to create one off payment:
With this option, the user will be present with additional fields to control certain values on the payment to be created:
Scheduled Charge Date: Will be the created contribution receive_date, it is today date by default but the user can change it.
Amount exc Tax: The amount of the payment (contribution) excluding the tax, it will be automatically set and pro rated based on the following formula:[(The number of days between the select membership start and end date) * The price of the membership per day based on its membership type length and fee]. The user also change this value if they desire.
Financial Type: The financial type that will be used on the contribution to be created, by default it is the "Financial type" of the membership that is selected, but the user can change it as well, changing it will affect the tax amount given not all financial types are linked to tax account.
Amount inc tax: Read-only field, which is the total amount of the contribution including the tax, this will be automatically calculated, and might change if the user changes the Amount exc Tax or the Financial Type.
Send confirmation email?: If selected, an email will be sent to the contact that we are adding the membership line item for, it is a replica of the CiviCRM sends confirmation emails for contributions, and it will only be sent if the contact has an email, here is an example of such email:
Given the contribution is linked to a membership, CiviCRM will by default uses "Memberships - Receipt (on-line)" mailing template
When the user submit the form, the following will happen:
1- New Membership with the selected type and dates will be created
2- New membership subscription line item will be created on the payment plan, which the user can see inside the manage instalments screen, the amount of that line item is Amount exc Tax and tax amount for the line item will be (Amount inc tax - Amount exc tax), and it will automatically renew with the rest of the payment plan (unless the user ticks the auto renew checkbox off when adding the line item).
3- New pending Contribution, the contribution total amount will = ((Amount inc tax), and the 'receive_date' will = the Scheduled Charge Date, and it will be linked to the membership (through the MembershipPayment entity) and to the payment plan (through the contribution_recur_id field on the contribution).
Technical Details
The work in this PR adjusts the code inside js/CurrentPeriodLineItemHandler.js, so instead of showing a validation error toast message when adding a line item to a completed payment plan, it now uses CRM.loadForm to either load the form at the following path:
The rest of the PR implements the form that the user sees when visiting the first path (the one related to adding membership line item), where the 2nd path will be implemented in another PR.
The form itself is a standard CiviCRM quickform, where the template file of the form contains supporting JS code that is mostly related to updating the "Amount inc tax" field whenever the "Amount exc tax" or the financial type change, and for that calculation new API end point was introduced which is ContributionRecurLineItem.calculatetaxamount, that takes the amount and the financial type, and calculated the total amount including tax using such information.
When it comes to the form itself, it operates in two modes, one is when paying without payment PAYMENT_TYPE_NO_PAYMENT and the other is when making a one off payment PAYMENT_TYPE_ONE_OFF_PAYMENT, both modes are very similar where the main differences are:
1- In "No Payment" mode the subscription line item amount will be 0 where in "One off payment" mode it will contain the submitted value.
2- In "No Payment" no contribution will be created, where in "One off Payment" a contribution will be created, that contribution will also be linked to the membership through the MembershipPayment entity, and to the recurring contribution through the contribution contribution_recur_id field.
3- In "On off payment" an email will be sent if the user select "send confirmation email", this was implemented using the core Contribution.sendconfirmation API.
Here is a diagram that shows the entities (in green) that will get created after submitting the form with "No Payment" option:
Overview
Making the manage instalments screen more flexible, where the user can now add a membership line item, even when all the instalments within the payment plan are completed (paid).
Before
Currently, the ability to add new membership line item (or even a normal line item) is not supported in Membershipextras when all the the instalments (contribution) within the payment plan are completed (paid), and an error toast message is shown when the user tries to do so.
After
Instead of showing the error toast message mentioned in the "before" section above, we now present two options to the user, the first is to create the membership without charging the user for it in the current period:
With this option, the following happen:
1- New Membership with the selected type and dates will be created 2- New membership subscription line item will be created on the payment plan, which the user can see inside the manage instalments screen, the amount of that line item is 0, and will automatically renew with the rest of the payment plan (unless the user ticks the auto renew checkbox off when adding the line item). though for the autorenewal to pick the price of the membership correctly at autorenewal , the Membershipextras "Use latest price when auto renew membership" setting should be enabled:
The second option is to create one off payment:
With this option, the user will be present with additional fields to control certain values on the payment to be created:
Scheduled Charge Date: Will be the created contributionreceive_date, it is today date by default but the user can change it.Amount exc Tax: The amount of the payment (contribution) excluding the tax, it will be automatically set and pro rated based on the following formula:[(The number of days between the select membership start and end date) * The price of the membership per day based on its membership type length and fee]. The user also change this value if they desire.Financial Type: The financial type that will be used on the contribution to be created, by default it is the "Financial type" of the membership that is selected, but the user can change it as well, changing it will affect the tax amount given not all financial types are linked to tax account.Amount inc tax: Read-only field, which is the total amount of the contribution including the tax, this will be automatically calculated, and might change if the user changes theAmount exc Taxor theFinancial Type.Send confirmation email?: If selected, an email will be sent to the contact that we are adding the membership line item for, it is a replica of the CiviCRM sends confirmation emails for contributions, and it will only be sent if the contact has an email, here is an example of such email:When the user submit the form, the following will happen:
1- New Membership with the selected type and dates will be created 2- New membership subscription line item will be created on the payment plan, which the user can see inside the manage instalments screen, the amount of that line item is
Amount exc Taxand tax amount for the line item will be (Amount inc tax - Amount exc tax), and it will automatically renew with the rest of the payment plan (unless the user ticks the auto renew checkbox off when adding the line item). 3- New pending Contribution, the contribution total amount will = ((Amount inc tax), and the 'receive_date' will = theScheduled Charge Date, and it will be linked to the membership (through the MembershipPayment entity) and to the payment plan (through the contribution_recur_id field on the contribution).Technical Details
The work in this PR adjusts the code inside
js/CurrentPeriodLineItemHandler.js, so instead of showing a validation error toast message when adding a line item to a completed payment plan, it now usesCRM.loadFormto either load the form at the following path:in case of adding membership line item
or the one at this path:
in case of adding non membership line item.
The rest of the PR implements the form that the user sees when visiting the first path (the one related to adding membership line item), where the 2nd path will be implemented in another PR.
The form itself is a standard CiviCRM quickform, where the template file of the form contains supporting JS code that is mostly related to updating the "Amount inc tax" field whenever the "Amount exc tax" or the financial type change, and for that calculation new API end point was introduced which is
ContributionRecurLineItem.calculatetaxamount, that takes the amount and the financial type, and calculated the total amount including tax using such information.When it comes to the form itself, it operates in two modes, one is when paying without payment
PAYMENT_TYPE_NO_PAYMENTand the other is when making a one off paymentPAYMENT_TYPE_ONE_OFF_PAYMENT, both modes are very similar where the main differences are:1- In "No Payment" mode the subscription line item amount will be 0 where in "One off payment" mode it will contain the submitted value. 2- In "No Payment" no contribution will be created, where in "One off Payment" a contribution will be created, that contribution will also be linked to the membership through the MembershipPayment entity, and to the recurring contribution through the contribution contribution_recur_id field. 3- In "On off payment" an email will be sent if the user select "send confirmation email", this was implemented using the core
Contribution.sendconfirmationAPI.Here is a diagram that shows the entities (in green) that will get created after submitting the form with "No Payment" option:
And this with "One off payment option":