Accessing buildOptions() instead of PseudoConstant

[nickholden]

I'm trying to build a custom search, and was looking at the Activity search that comes with Civi. It uses various calls to CRM_Core_PseudoConstant to populate details of such as possible activity status or activity type. But in the code comments for CRM_Core_PseudoConstant::activityType() it says "Deprecated - please use  the buildOptions() method in the appropriate BAO object."

I have tried to find some documentation about using buildOptions() but things seem a little sparse. There isn't even much mention of it in the forum. Could someone please explain how I could use buildOptions() to construct a list of activity types (preferably all activity types available to the CiviCase component not just those restricted to contacts directly)?

Thanks

Nick

[nickholden]

I've made some progress, so replying to my own question to begin to document this, and also to ask a follow up, more general question.

The specific solution I needed was:

Code: [Select]

    $activityType = array('' => ' - select activity - ') + CRM_Activity_BAO_Activity::buildOptions('activity_type_id');

What stumped me was that the option I needed to specify was 'activity_type_id' rather than 'activity_type' (which is what the API uses to generate the same result). It also took me a while to work out precisely which class I needed to reference (which is probably obvious once you get used to doing this, but the documentation talks about the use of CRM_*_BAO_*::buildOptions, and that is just too much wildcard for a newbie to deal with).

So, my follow up question: I can understand why the new approach is preferable to the use of PseudoConstant, but how can a novice developer discover, for any particular entity and attribute or field that they want to access the options for, what the correct class and parameters are? The developer notes on the jira task (12464) says "All fields with option lists now declare that info in the schema metadata" which sounds great, but I have to confess I have no idea how to access that information.

When learning the API I can play around with the API explorer, but there doesn't seem to be a straightforward way to translate what I discover works in the API explorer into the correct syntax for using buildOptions(). I don't want to fall back on lots of API calls inside my custom search if I don't need to do that, but I do need an easy reference for the entities and parameters that make sense when using buildOptions(). Is that a possibility?

[Coleman Watts]

Here is the documentation:
http://wiki.civicrm.org/confluence/display/CRMDOC/Pseudoconstant+%28option+list%29+Reference

[nickholden]

Hi Coleman,

Thanks for the link. I had read that page, several times. Maybe I'm not smart enough to be a Civi developer, but I was still confused. Maybe I just needed a few more examples to orient myself. Is there a way to find / deduce the correct classes and parameters for a particular option list?

[Coleman Watts]

A little background: Prior to 4.4 option lists were sort of floating out in space somewhere, not really connected to anything else. So if for example you wanted to retrieve the option list for a contact's preferred communication method you had to "just know" that the way to get it was by calling CRM_Core_Pseudoconstant::pcm().
Now in 4.4 we're using metadata to "tell" the schema what option list goes with what field. The upshot of that is that all you need is the name of the entity+field and you can get the option list. No secret handshake needed.
CRM_*_BAO_* refers to the PHP object associated with the database table. Generally every table in the database has a BAO class as well as an api method. I think using the api is generally preferred. In the case of getoptions it's just a thin wrapper around CRM_*_BAO_*::buildOptions.
Some examples:
civicrm_api3('contact', 'getoptions', array('field' => 'preferred_communication_method'));
civicrm_api3('contact', 'getoptions', array('field' => 'gender_id'));
civicrm_api3('activity', 'getoptions', array('field' => 'activity_type_id'));

Note that unlike 'pcm' which was just some random nickname that someone conceived, with this new getoptions api we are passing in the actual name of the field that's in the schema.

To use your example below, the reason "activity_type" did not work is because it's not the real name of a field in the civi database (again, like pcm, it's just some random nickname). It may work in the api because someone has defined an alias in the api for some backward-compatability purpose, but "activity_type_id" would work as well and it's the "real" way to do it.

The advantages of using real field names rather than random nicknames:

• You don't have to know any secret words
• It works consistently for every field
• You can write much cleaner code. No need for a bunch of arrays in your code that map field names to pseudoconstant methods.

For example, in my webform_civicrm project I was able to eliminate about 500 lines of code in version 4 that was all dedicated to looking up option lists for fields in all the random different ways it needed to be done. Replaced it all with a single line that looks like:
$options = civicrm_api3($entity, 'getoptions', array('field' => $field_name);

[nickholden]

Thanks, Coleman. I feel the mist parting already.