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 additional due amount, this leads to incorrect financial entries and Contribution status still kept to 'Partially Paid'.

Objectives

1. Avoid polluting user experience with (a large number of) price field or price set entries that the user should not change and doesn't need to know about.
2. Avoid creating a large number of entries in config tables like price set and price field when users are doing normal things like ad hoc line item entries.
3. Avoid confusing users by allowing them to edit price sets for events that have registrants against them, and make it confusing which of several pricesets are relevant for a particular event.

Observations

1. We can hide pricesets using civicrm_price_set.is_quick_config=1. We can prevent editing of a priceset by setting civicrm_price_set.is_reserved=1.
2. Price fields associated with a hidden priceset are also hidden.
3. Two hidden, reserved pricesets are created on install, one for contributions (id=1) and one for memberships (id=2). No hidden, reserved pricesets are created for registrants.
4. Editing a event registration is possible and uses the price set and price fields. It is not possible to delete a price field that is in use.
5. If a priceset and its fields is copied, then registrations made with it could still be edited. Ideally any change made to one price set would affect all copies of it so they stayed in sync. However, this is not a good solution.
6. Price fields have a visibility_id field. Values are Public and Admin from an option_value group (37). This option value group is shared with visibility fields on other objects. It does not seem easy/feasible to add a third option, Hidden, that would never appear in the UI.
7. It might be reasonable when an admin adds a line item in the back office to a contribution made with a price set that a price field visible just to admins would be added, especially if the user interface that creates the additional line item makes clear that it is adding a field to the priceset.

Tests

1. Inserting a price field into priceset 1 (default contribution quick config) did not change the create or edit experience.
2. Inserting a price field into priceset 2 (default membership quick config) did not change the create or edit experience.

Proposal

Keeping in mind both the limitations here's an approach to support adding multiple line-items.

On the Add Line Item form, in addition to allowing selection of unused price fields, always provide an additional option: '

Create new item

'. If it is selected, create a new price field and price field value record as follows:

1. Default values for new price_field record:
   1. set price_set_id to whatever is the priceset associated with the contribution being edited
   2. label: 'Additional Line Item'
   3. html_type: Text
   4. is_enter_qty: 1
   5. weight: (largest pf.weight in ps) + 1
   6. name: additional_line_item (we should likely fix core to make this unique, and then use algorithm for that to generate this unique name)
2. Default values for new price_field_value record:
   1. price_field_id: newly created PF record above
   2. label: 'Additional Contribution Amount'
   3. (for rest, follow what happens when a new price field is defined via browser)
   4. name: again, this should be unique but isn't.