How to populate a structure dropwdown

By default, ATiM2 structure dropdowns are populated from the Value Domain and Permissible Values datatables. This guide will show a developer the alternatives.

Contents 1 The basics 2 How to implement a dropdown with data from a model 2.1 How to filter down the values 3 How to implement a dropdown with custom user values

The basics

The aliases of dropdowns used in ATiM are located in the table structure_value_domains. Two things need to be done to have a custom dropdown.

1. Provide a source to our dropdown alias (still in the database). The source is a function that will be called to generate the dropdown.
2. In the code, have a function that returns an array containing arrays with two keys.

• default: The string that will be displayed
• value: What to record in the datatable

How to implement a dropdown with data from a model

For an example, you might populate this new "source" field with the following...

Clinicalannotation.Icd10::permissibleValues

...which says in the "Clinicalannotation" plugin, there is an "Icd10" model, and we should get the dropdown options from the "permissibleValues" function in there.

The function would look like this...

function permissibleValues() {
	$return = array();
	
	foreach ( $this->find('all',array('order'=>'Icd10.id ASC')) as $icd10 ) {
		$return[$icd10['Icd10']['id']] = 
			$icd10['Icd10']['id'].' - '.__($icd10['Icd10']['description'],TRUE);
	}
	
	return $return;
}

In this case, the function does a find over the model, sorts it, and returns an array result. The "value" to record in the database is stored as the $result key and the label to display to the user is the assignation of that key.

How to filter down the values

The source function has limitations: it cannot pass parameters to the called function. So what should you do if you need to? Here is a reminder, the called function needs to return a dropdown. It does not necessarily need to generate it on call! Hence, here is a trick.

1. Declare a static variable in your model.
2. In your controller, before setting the structure, generate your dropdown and assign it to your static variable.
3. In your model, create a function that returns the static variable with your dropdown.
4. Define that function as the source of your structure_value_domain.

Then when the structure is loaded the generated dropdown will be loaded.

How to implement a dropdown with custom user values

1. Create a control name for you custom dropdown in structure_permissible_values_custom_controls
2. Define the source of your dropdown as "StructurePermissibleValuesCustom::getCustomDropdown('{control name}') where {control name} is the name of your control.

This is it! If you want to add predefined custom values to your dropdown, that's done in structure_permissible_values_customs.