APIv4 Option Lists¶
Some fields in CiviCRM are linked to an option list (aka Pseudoconstant). These fields are typically shown to the user as checkboxes, radios, or a dropdown-select of options from the pseudoconstant list.
The API provides tools for working with such fields; so that downstream developers do not need to translate between database values and option properties.
Option list properties¶
All option lists consist of at least:
- id: The value stored by a field
- name: Non-changing string identifier
- label: Translatable label shown to user
Some option lists also contain
- description: Text description shown to the user in select2 lists
- abbr: Abbreviation (used with country and state/province lists)
- icon: CSS class used to produce an icon for an option
- color: Hex value of the color for an option
Which fields have option lists?¶
To find out which fields have option lists for a particular entity, use the
getFields action from the API or API Explorer, e.g.
civicrm_api4('Contact', 'getFields' [ 'where' => [['options', '!=', FALSE]], ])
Retrieving an option list¶
If you need to retrieve the full option list for a field, use the
getFields action and set the
to an array of the above properties you would like to retrieve. Try it in the API explorer, e.g.
civicrm_api4('Contact', 'getFields' [ 'where' => [['name', '=', 'contact_type']], 'loadOptions' => ['name', 'label', 'description'], ])->first();
contact_typefield including the list of available options (names will be ['Individual', 'Household', 'Organization'], labels will be localized translations if the site is not in English).
Unless you are building a form and need to render an option list for the user to select, in most cases
you will not need to query
getFields to e.g. match option ids to labels. The syntax below can automatically
perform such transformations.
When reading or writing data from the API, a special suffix tells the API to transform between option ids and other properties. For example:
Activity::create() ->addValue('activity_type_id:name', 'Meeting') ...
Using this syntax saves you from needing to look up the id of an activity type. It also makes your code more portable, as option ids can change from one database to another, but names are consistent.
Get operations use the same syntax to reverse the lookup and transform an option id to another property.
Activity::get() ->addSelect('*', 'activity_type_id:label', 'activity_type_id:icon') ...
This tells the API to return all fields (
*) plus the label and icon of the activity type, giving the data needed for a user-facing display.
Option Lists or Joins
The syntax for option transformations looks very similar to implicit joins (the difference being a colon instead of a dot). Your choice of which to use depends on the field.
For example, the Contact
gender_id field has an option list but not a foreign key, so you must use the option syntax (
But the Event
campaign_id field has a foreign key instead of an option list, so you would use a join (