APIv4 - Allow field options to be returned in multiple formats

[colemanw]

Overview

Gives more flexibility about how options are returned from APIv4.
Added visibility in the API explorer.

Before

In GetFields, loadOptions is a boolean param, and the option list returned is single-dimensional.

After

In GetFields, loadOptions can be either a boolean or an array. If an array, the option list returned will contain the keys requested.

Technical Stuff 👀

Field pseudoconstants are stored in many different places (option_values table, other tables, callbacks, etc.) but that all gets normalized when they pass through DAO::buildOptions() which returns a one-dimensional list. Well and good, but some option lists contain other info (icon, color, description...), and that flat list has been a source of growing pains.

The end goal behind this PR is to standardize what a multi-dimensional pseudoconstant list looks like. The idea is that regardless of how the options are stored and what the columns in that table look like, when reading/writing an option list (via the api anyway) the array keys will look like this:

• id: the machine name stored for this option (in the civicrm_option_values table this maps to value column, in other tables it usually maps to id)
• name: the machine name of this option (if different from id; sometimes they are the same thing)
• label: translatable label (the API will return this in the current language).
• description: text description of this option (displays in small font in select2 lists).
• color: e.g. #aabbcc
• icon: e.g. crm-i fa-rocket 🚀

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[totten]

This sounds sweet. :)

[eileenmcnaughton]

I haven't looks at the code but I like the pr description!

[eileenmcnaughton]

OK - so code is constrained to apiv4 - it feels like a contract change - what will the impact be?

[colemanw]

@eileenmcnaughton it's backward-compatible. Passing in the same api params will still get you the same result, so no impact on current code. But it adds support for a new way of passing in the param that will get you the multi-dimensional result.

[eileenmcnaughton]

nice

[colemanw]

Ok I think this is good now; it does everything I envisioned and has exposure in the Explorer + sufficient test coverage.

[eileenmcnaughton]

@colemanw sorry we broke it. Happy to MOP it & you can merge once tests pass on the rebased version

[eileenmcnaughton]

unrelated fails