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 that has all of the fields in its price set used, the Add item(s) option continues to show:

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.

While it is possible to create a new price field every time a new ad hoc line item is added (we did this on a custom build for one client on a budget), we recommend building on the pattern used for quick config of contribution amounts and memberships. In both cases, a special price field is used that is not exposed for editing through the Price Fields configuration screens. Balancing ease of implementation against likely use cases, we propose to add 25 hidden price fields. This will allow up to 25 line items to be added to a contribution before an error message is displayed saying "The maximum number of line items has been reached." (Would a different number like 15 or 50 be more appropriate? We don't feel like coding the ability to extend this indefinitely.) Tech savvy administrators will be able to increase this number by inserting records into the database.

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.