Plugins, Hooks, & External Modules
Developer methods for
Plugins, Hooks, & External Modules
Hook functions
REDCap Developer Tools:
Documentation for Plugins, Hooks, & External Modules
REDCap Version 14.9.1
REDCap::getInstrumentNames
(REDCap >= 5.11.0)
REDCap::getInstrumentNames
— Returns a list of data collection instruments (both unique instrument name and label) for the current project
Description
mixed REDCap::getInstrumentNames ( [ mixed $instruments = NULL ] )
Returns a list of data collection instruments (both unique instrument name and label) for the current project. If $instruments parameter is supplied (as array or string), it will only return the data collection instrument(s) provided in the array or string. If $instruments is specified for a single data collection instrument, it will return only the label for that instrument.
NOTE: If the project is in production status with Draft Mode enabled, it will NOT output any of the instruments from Draft Mode. It will always only output the instruments as they are seen on data entry forms and survey pages, regardless of the project's development/production status.
NOTE: If the project is in production status with Draft Mode enabled, it will NOT output any of the instruments from Draft Mode. It will always only output the instruments as they are seen on data entry forms and survey pages, regardless of the project's development/production status.
Parameters
instruments
If provided as an array of data collection instrument names (i.e. the unique name, not the instrument label), it will return an array of only those instruments. If provided as a single instrument name (string), it will return only the label for that instrument. By default, NULL is used, in which it will return all instruments for the entire project.
If provided as an array of data collection instrument names (i.e. the unique name, not the instrument label), it will return an array of only those instruments. If provided as a single instrument name (string), it will return only the label for that instrument. By default, NULL is used, in which it will return all instruments for the entire project.
Return Values
Returns array of instrument labels with their corresponding unique instrument name as array keys. The instruments are ordered in the order in which they are specified in the project. If $instruments is provided as a single instrument name (string), it will return only the label for that instrument.
Restrictions
This method can ONLY be used in a project context (i.e. when "pid" parameter is in the query string of the plugin URL) or else a fatal error is produced.
Examples
Example #1:
This example shows how to simply display the unique instrument name and label of all data collection instruments in a project.
// Print out the names of all instruments in the project
$instrument_names = REDCap::getInstrumentNames();
foreach ($instrument_names as $unique_name=>$label)
{
// Print this instrument name and label
print "$unique_name => $label,\n";
}
Example #2:
This example illustrates how to get the label of a single instrument.
// We have our unique instrument name $unique_name = 'enrollment_form'; // Get the label of our instrument $instrument_label = REDCap::getInstrumentNames($unique_name);
REDCap 14.9.1 - © 2024 Vanderbilt University