Allow Item(s) to be added where not currently allowed

Overview

When editing a price set contribution that has not had all of its fields used it is possible to add a new line item. But there has been no way to create a line item when creating a new contribution or when editing quick config contributions or when editing contributions that have all price set fields used. This issue allows users to add arbitrary line items in these contexts. New price fields are added as required to the price set used by the contribution. When the price set is reused, these fields are available for reuse.

Current UI

Currently it is not possible to add items to contributions that were created via Quick Config rather that with full price sets. Only when editing contributions created with price sets is it possible to add items, and then only for line item options in the price set that have a quantity of null or 0.

For example, for a price set with three items like this:

Suppose a contribution is created that uses two of them:

Then when editing it there will be an option to add a line item of the third, but this is the only option:

Current Data

When the edits to a line item would require a change to the configuration of the price set, such as a change in the price of an option, the change is not made to the original price set fields or their option values but just to the values stored for this contribution in the line_item table, with total values flowing from that table to financial_item, entity_financial_trxn and financial_trxn.

Also recall that all quick config price sets for contributions use a single hidden placeholder price field (eg civicrm_line_item.price_field_id=1), and the same is true for memberships (eg civicrm_line_item.price_field_id=2).

Proposed UI

On the New Contribution form, whether opened from menu or for a specific contact, we want to allow Adding item(s) in addition to specifying a Total Amount or choosing a pre-existing price set:

Similarly, for a contribution created via Quick Config, we will add this option:

And for a contribution created with a complex price set used, the Add item(s) option is also changed from a link to a select widget:

In all of these cases, the Add Item link will add rows allowing new items to be specified, as follows:

Proposed Data

It is possible to use the current schema to implement this new functionality. However, as each contribution has to use one price set, and each line item needs a unique price field / price field value combination from that priceset, the extension will need to create appropriate entries in the price field and price field value tables.

The UI as we saw above for adding this is as follows: When displaying price fields / price field values in the select widget for adding an item, in addition to allowing selection of unused price fields, always provide an additional option: 'Create new item'. If it is selected, the extension will 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' & number of price fields in the priceset + 1
   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.

A slight downside to this approach is that the newly added price field and price field value will then be visible when adding items to other contributions that use this price set. It will also be visible when adding contributions in the backend using the price set. However, it will not be displayed in frontend forms.

Testing

Test the following:

1. Use links everywhere defined to create new items.
2. Verify the receipt messages.
3. Edit the items and check the contribution is valid and that receipt is valid for
   1. New contributions
   2. New item on Quick Config contributions
   3. New item on price set contributions without all price set fields used
   4. New item on price set contributions with all price set fields used
   5. New item on price set contributions with all price set fields used then one set to qty=0.
4. Create unit tests as appropriate.