redcap_survey_page
(REDCap >= 5.11.0)
redcap_survey_page
— Allows custom actions to be performed on a survey page
Description
void redcap_survey_page ( int $project_id, string $record = NULL, string $instrument, int $event_id, int $group_id = NULL, string $survey_hash, int $response_id = NULL, int $repeat_instance = 1 )
Allows custom actions to be performed on a survey page. You may utilize this hook to 1) perform back-end operations, such as adding or modifying data in database tables, which can be done when the page loads or when triggered by a user action on the page via JavaScript, or 2) output custom HTML, JavaScript, and/or CSS to modify the current page in any way desired.
NOTE: This hook function does not get executed after the survey is completed (i.e., on the Survey Acknowledgment page). If you wish to perform an action after the survey has been completed, you should use the redcap_survey_complete() hook function.
Location of Execution
The function is executed at the very BOTTOM of every survey page (after the survey has been rendered).
Parameters
project_id
The project ID number of the REDCap project to which the survey belongs.
record
The name of the record to which the current survey response belongs, assuming the response has been created. If the record/response does not exist yet (e.g., if participant is just beginning the first survey), its value will be NULL.
instrument
The name of the data collection instrument (i.e., the unique name, not the instrument label) to which this survey corresponds. This corresponds to the value of Column B in the Data Dictionary.
event_id
The event ID number of the current survey response, in which the event_id corresponds to a defined event in a longitudinal project. For classic projects, there will only ever be one event_id for the project.
group_id
The group ID number corresponding to the data access group to which this record has been assigned. If no DAGs exist or if the record has not been assigned to a DAG, its value will be NULL.
survey_hash
The hashed string of alphanumeric text in the survey link (i.e., the "s" parameter in the query string of the survey URL). NOTE: If this is a public survey, the survey hash will always be the same for every participant.
response_id
The response ID number of the current survey response, in which the response_id originates from the redcap_surveys_response database table. The response_id is particular to a specific record-event_id pair for the given survey. If the record does not exist yet (e.g., if participant is just beginning the first survey), the response_id value will be NULL.
repeat_instance
(only used for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal). Default value = 1. NOTE: This parameter was added in REDCap 7.3.4.
Return Values
Nothing. Your function does not need to return anything.
Examples
Example #1:
This example illustrates how to perform desired operations for ALL surveys, such as displaying static HTML at the bottom of EVERY survey page.
function redcap_survey_page($project_id, $record, $instrument, $event_id, $group_id, $survey_hash, $response_id, $repeat_instance)
{
print '<div class="yellow">Special announcement text to display at the very bottom of every survey.</div>';
}
Example #2:
This example shows a simple way of performing project-specific actions using the $project_id parameter. NOTE: This particular method is not as clean or as easy to maintain for many projects at once. See the next example for a better way to implement project-specific actions for many projects.
function redcap_survey_page($project_id, $record, $instrument, $event_id, $group_id, $survey_hash, $response_id, $repeat_instance)
{
// Perform certain actions for specific projects (using "switch" or "if" statements).
switch ($project_id) {
// Perform operations for project_id 212
case 212:
// do something specific for this project ...
break;
// Perform operations for project_id 4775
case 4775:
// do something specific for this project ...
break;
// ...
}
}
Example #3:
A much more manageable way to perform project-specific operations for many projects at once is to create a directory structure where each project has its own subdirectory under the main Hooks directory (e.g., named "redcap/hooks/pid{$project_id}/redcap_survey_page.php"). This allows the code for each project to be sandboxed and separated and also makes it more manageable to utilize other files (e.g., PHP, HTML, CSS, and/or JavaScript files) that you can keep in the project's subdirectory (i.e., "pid{$project_id}") in the Hooks folder. Then the designated project handler PHP script can utilize any of the parameters passed in the function to perform actions specific to each project. NOTE: This example assumes that the "hooks" sub-directory is located in the same directory as the PHP file containing the Hook functions.
function redcap_survey_page($project_id, $record, $instrument, $event_id, $group_id, $survey_hash, $response_id, $repeat_instance)
{
// Set the full path of the project handler PHP script located inside the
// project-specific sub-folder, which itself exists in the main Hooks folder.
$project_handler_script = dirname(__FILE__) . "/hooks/pid{$project_id}/redcap_survey_page.php";
// Check if the project handler PHP script exists for this project, and if so,
// then "include" the script to execute it. If not, do nothing.
if (file_exists($project_handler_script)) include $project_handler_script;
}