redcap_survey_acknowledgement_page
(REDCap >= 10.2.0)
redcap_survey_acknowledgement_page
— Allows custom actions to be performed on a survey's acknowledgement/"thank you" page immediately after the survey has been completed.
Description
void redcap_survey_acknowledgement_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's acknowledgement/"thank you" page immediately after the survey has been completed, in which it is called immediately after the Survey Acknowledgment Text (and after the Survey Queue table, if displayed) is output onto the 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.
Location of Execution
The function is executed on a survey immediately after the survey has been completed immediately after the Survey Acknowledgment Text (and after the Survey Queue table, if displayed) has been output onto the page.
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 the survey page after the survey has been completed.
function redcap_survey_acknowledgement_page($project_id, $record, $instrument, $event_id, $group_id, $survey_hash, $response_id, $repeat_instance)
{
print '<div class="yellow">Special announcement text to display right below the survey acknowledgment text.</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_acknowledgement_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_acknowledgement_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_acknowledgement_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_acknowledgement_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;
}
Example #4:
This example provides a simple illustration of how one might redirect participants (after they complete a survey) to a custom webpage while passing the record name in URL, which might be done in order to display something to the participant that is particular to them or to process/save something regarding that participant (e.g., save something in a database table or send an email). NOTE: The PHP script below is the project handler script that gets included by the Hook function, as seen in the previous example.
<?php
// This is a project handler script with filename ...redcap/hooks/pid1256/redcap_survey_acknowledgement_page.php
// This script is only included by surveys completed in project_id 1256
// Only perform the redirection for the survey corresponding to the instrument 'diabetes_questionnaire'
if ($instrument == 'diabetes_questionnaire')
{
// Redirect the participant to the custom URL appended with the record name
redirect("https://mywebsite.edu/redcap/plugins/process_questionnaires.php?record=" . $record);
}