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::getDataDictionary
(REDCap >= 6.8.0)
REDCap::getDataDictionary
— Returns the Data Dictionary of fields for a given project
Description
mixed REDCap::getDataDictionary ( [ int $project_id, ] [ string $returnFormat = 'csv' [, bool $exportCsvHeadersAsLabels = TRUE [, mixed $fields = NULL [, mixed $instruments = NULL [, bool $draftMode = FALSE ]]]]] )
Returns the Data Dictionary (i.e., metadata) of fields for a given project in a specified format. If $fields parameter is supplied as an array (or a string as a single field), it will only return those fields.
Parameters
project_id (optional)
The project ID number of the REDCap project from which to pull metadata. If not provided in a project-level plugin, it will assume the current project ID of the plugin and will also infer return_format to be the first parameter passed to the method. If project_id is not provided in a system-level plugin, it will throw a fatal error.
The project ID number of the REDCap project from which to pull metadata. If not provided in a project-level plugin, it will assume the current project ID of the plugin and will also infer return_format to be the first parameter passed to the method. If project_id is not provided in a system-level plugin, it will throw a fatal error.
returnFormat
The format in which the Data Dictionary should be returned. Valid options: 'array', 'csv', 'json', and 'xml'. By default, 'csv' is used.
The format in which the Data Dictionary should be returned. Valid options: 'array', 'csv', 'json', and 'xml'. By default, 'csv' is used.
exportCsvHeadersAsLabels
Sets the format of the CSV headers returned (only applicable to 'csv' return formats). If FALSE, it returns the unique header names (with lowercase letters and underscores) - e.g., "field_name". If TRUE, it returns the human-readable text as the headers (as seen when downloading the Data Dictionary in the normal web interface) - e.g., "Variable / Field Name". By default, TRUE is used, but if returnFormat is not 'csv', then it is set to FALSE automatically.
Sets the format of the CSV headers returned (only applicable to 'csv' return formats). If FALSE, it returns the unique header names (with lowercase letters and underscores) - e.g., "field_name". If TRUE, it returns the human-readable text as the headers (as seen when downloading the Data Dictionary in the normal web interface) - e.g., "Variable / Field Name". By default, TRUE is used, but if returnFormat is not 'csv', then it is set to FALSE automatically.
fields
An array of field variable names, or alternatively a single field variable name (as a string). This will limit the Data Dictionary returned to only those fields specified. By default, NULL is used, which will return all fields from the given project. NOTE: The "fields" and "instruments" parameters are additive and can be used together.
An array of field variable names, or alternatively a single field variable name (as a string). This will limit the Data Dictionary returned to only those fields specified. By default, NULL is used, which will return all fields from the given project. NOTE: The "fields" and "instruments" parameters are additive and can be used together.
instruments
If provided as an array of data collection instrument names (i.e. the unique name, not the instrument label), it will limit the Data Dictionary returned to only those instruments specified. If provided as a single instrument name (string), it will limit the Data Dictionary returned to only the specified instrument. By default, NULL is used, in which it will return all fields for the entire project. NOTE: The "fields" and "instruments" parameters are additive and can be used together.
If provided as an array of data collection instrument names (i.e. the unique name, not the instrument label), it will limit the Data Dictionary returned to only those instruments specified. If provided as a single instrument name (string), it will limit the Data Dictionary returned to only the specified instrument. By default, NULL is used, in which it will return all fields for the entire project. NOTE: The "fields" and "instruments" parameters are additive and can be used together.
draftMode
If set to TRUE while the project is in production status *and* in draft mode, it will return the drafted changes of the Data Dictionary that have not yet been appproved for production use. If FALSE, it returns the normal Data Dictionary of fields that are in use. By default, FALSE is used.
If set to TRUE while the project is in production status *and* in draft mode, it will return the drafted changes of the Data Dictionary that have not yet been appproved for production use. If FALSE, it returns the normal Data Dictionary of fields that are in use. By default, FALSE is used.
Return Values
Returns the Data Dictionary of fields in the specified format. Note: If returnFormat is 'array', the array key of each field will be the field's "field_name".
Examples
Example #1:
This example shows how one can obtain an array of all fields and their attributes for a project to perform a specific action for each field.
// Get the data dictionary for the current project in array format
$dd_array = REDCap::getDataDictionary('array');
// Loop through each field and do something with each
foreach ($dd_array as $field_name=>$field_attributes)
{
// Do something with this field if it is a checkbox field
if ($field_attributes['field_type'] == "checkbox") {
// Something
}
}
Example #2:
This example shows how one can get the data dictionary in CSV format just like one would download via the normal web interface for project_id=545.
// Get the CSV data dictionary with labels $dd_csv = REDCap::getDataDictionary(545);
Example #3:
Get the data dictionary of drafted changes in JSON format for project_id=1124.
// Get the drafted changes in JSON format $dd_json = REDCap::getDataDictionary(1124, 'json', false, null, null, true);
Example #4:
Get an array of just two fields for the current project.
// Get two fields' attributes as an array
$fields = array('dob', 'mrn');
$dd_array = REDCap::getDataDictionary('array', false, $fields);
REDCap 14.9.1 - © 2024 Vanderbilt University