limitation+propsal-for-add-line-item.md

Limitations

1. A contribution cannot have multiple line-items which share same price_field_id and/or price_field_value_id because there is a unique key defined for line-item table which expects unique combination of these attributes
2. A contribution cannot have multiple line-items linked with price fields of different price-sets, otherwise it will cause a issue while doing 'Record Payment' as I tested on local by relaxing the crieria to allow user to add line-item linked to price fields of different price sets. Add after paying the addtional due amount, leads to incorrect financial entries and Contribution status still kept to 'Partially Paid'.

Proposal

Keeping in mind both the limitations here's what my approach to support add multiple line-items.

New Contribution with quick-config price field

1. On this page if user chose to use text price field 'Total Amount', then upon clicking the 'Add line item' link will add a inline list of fields (as described in graphic) essential to create a line-item.
2. The inline fieldset will contain 5 fields as per graphic and upon submit it will: 2.1. First create a quick config Text price-field (PF) against the existing (b/c we cannot have different price-set (PS) due to limitation 1) price-set (name=default_contribution_amount) and use it's ID and price-field-value (PFV) ID for the new line-item. 2.2. Choose new PF label as . 2.3. Before created the new PF check if there is any existing PF with same amount+FT, yes then use its PF and PFV ID for line-item or proceed with creating new PF. This is to avoid creating unecessary PF on line-item add.
3. There would be a limit provided as setting which will restrict user, not allow to create anymore of such PF to add line-item. If the limit is reached through a appropriate message to user.

New Contribution with non-quick-config price field

1. If user chose to use existing PF then upon clicking the 'Add line item' link will add a inline list of fields (as described in graphic) essential to create a line-item, with a additional field as 'Price Field' listing only the PFs of chosen PS because of Rule 1 and 2.
2. There will be a form validation to check the chosen PFs in the inline line-item field are distinct.
3. Although it is possible to create bogus PF to allow new line-items, but then those PF need to be added against existing PS with visibility=hidden but doing so aren't we affecting the configured PS of user? Also we cannot add PF to any other PS dur to Rule2.

Edit Contribution with quick-config price field

If the contribution is already created using quick-config PF then follow the steps of 'New Contribution' with quick-config price field

Edit Contribution with non-quick-config price field

If the contribution is already created using non-quick-config PF then follow the steps of 'New Contribution' with quick-config price field

Points to ponder:

1. We cannot create a separate quick-config(why choose quick-config? to keep it reserve) price-set to create those bogus PF, because of Rule 2. Suppose a user created a contribution with quick config 'Contribution Amount' and then if he keep on adding line-item on Edit Contribution form, creating bogus PF against different reserved price-set of ours will raise issue described in Rule 2. That's why we need to use existing quick-config PS to add those newly created bogus PF which will be later used in line-items.

2. To fullfill Rule 1 and 2 we have no other option for non-quick-config PS but to allow line-item to be created with it's existing available PF as how current extension is offering via 'Add Item' form.

Alogirthm

1. Check PF used in New Contribution, if quick-config go to 3, else go to 4
2. Check PF used in Edit contribution, if quick-config go to 3, else go to 5
3. Show 'Add line item' link, on click:
  3.1 Render inline line-item fields
  3.2 On submit check for existing PF under this PS which got same amount and FT
  3.3 If not found create new PF and its PFV under this PS and use it's PF and PFV ID for the new line-item.
  3.4 If found use it's PF and PFV ID for the new line-item
  3.5 Create new line-item and make appropriate financial entries which is already handled by ext.
4. Check PF used in New Contribution, if non-quick-config go to 6
5. Check PF used in Edit contribution, if non-quick-config go to 6
6. Show 'Add line item' link, on click:
   6.1 Render inline line-item fields of respective price-fields available to choose. Like 3 PF are not used up by line-items        so populate 3 inline fields against respective PF with prefilled PF value, FT, Qty and Amount.
   6.2 [Special case of 5] If all PFs are used up, then don't show this link and instead through a message to indicate the same
   6.7 Add form validation to ensure unique PFs are chosen for each line-item.
7. Proceed to create new PF as in 3.3 only when total no. of created PFs LTE max_allowed_pf_entries and later is a special CiviContribute setting offered by this extension on install.