One of the more powerful things that modules can do is to utilize REDCap Hooks, which allow you to execute PHP code in specific places in REDCap. For general information on REDCap hook functions, open Control Center, click Plugin, Hook, & External Module Documentation, and scroll down to the Hook functions section in the left menu. To use a hook in your module you must add a method in your module class with the exact same name as the name of the desired hook function. For example, in the ExampleModule class below, there is a method named redcap_project_home_page, which means that when REDCap calls the redcap_project_home_page hook, it will execute the module's redcap_project_home_page method.
<?php
namespace Vanderbilt\ExampleModule;
class ExampleModule extends \ExternalModules\AbstractExternalModule
{
// This method will be called by the redcap_data_entry_form hook
function redcap_data_entry_form($project_id, $record, $instrument, $event_id, $group_id, $repeat_instance)
{
// Put your code here to get executed by the hook
}
}Remember that each hook function has different method parameters that get passed to it (e.g., $project_id), so be sure to include the correct parameters as seen in the hook documentation for the particular hook function you are defining in your module class.
When used in an External Module, this hook must return an actual boolean value (either true or false). Do not return 0, 1, or other truthy/falsy values. The results of multiple modules using this hook will be combined with logical AND, i.e. as long as one implementation returns false, the email will not be sent by REDCap.
By default, every page hooks will only execute on project specific pages (and only on projects with the module enabled). However, you can allow them to execute on pages that aren't project specific by setting the following flag in config.json. WARNING: This flag is risky and should ONLY be used if absolutely necessary. It will cause your every page hooks to fire on literally ALL non-project pages (the login page, control center pages, "My Projects", etc.). You will need strict and well tested checking at the top of your hook to make sure it only executes in exactly the contexts desired:
"enable-every-page-hooks-on-system-pages": true
See Proposing New Hooks for instructions on how to propose additional hooks that any External Module can call.
The following hooks are available for use in external modules only:| Method |
Minimum REDCap Version |
Description |
|---|---|---|
| redcap_module_ajax($action, $payload, $project_id, $record, $instrument, $event_id, $repeat_instance, $survey_hash, $response_id, $survey_queue_hash, $page, $page_full, $user_id, $group_id) | 12.5.9 | Triggered by calling the ajax() method of the Javascript Module Object. $action (must be a string) and $payload are the parameters submitted to module.ajax(); the other parameters give context information that, when set, can be trusted to be correct (as with REDCap hooks). Allowed actions (in authenticated and non-authenticated contexts) must be explicitly declared in config.json through the auth-ajax-actions and no-auth-ajax-actions settings (arrays of strings), respectively. |
| redcap_module_api_before($project_id, $post) | 14.1.5 | Triggered just before REDCap's API is called (i.e., after REDCap has determined which API method is going to be called but before actually calling it). API requests may be disallowed by returning an error message string. The $post variable is a copy of $_POST with default values added and some values normalized or formatted. For example, if the REDCap API call is Export Records, then $post['content'] will be "record" and $post['action'] will be "export". Note: $post['action'] will not necessarily match the value of action in the body of the user's API request. The user's actual request details can be obtained by accessing the $_POST superglobal within the hook function. |
| redcap_module_configuration_settings($project_id, $settings) | 11.0.0 | Triggered when the system or project configuration dialog is displayed for a given module. This hook allows modules to dynamically modify and return the settings that will be displayed. |
| redcap_module_system_enable($version) | 9.0.0 | Triggered when a module is enabled or changed to a different version in Control Center. It is not recommended to use this hook as a primary means of determining when to transition modified module settings, as there are many edge cases that could conflict with such logic (e.g. temporarily downgrading a module). It is instead recommended to transition settings based solely on the state of the values currently stored. |
| redcap_module_system_disable($version) | 9.0.0 | Triggered when a module gets disabled on Control Center. |
| 9.0.0 | This hook is no longer used. Since REDCap 12.0.4 the redcap_module_system_enable() hook has been called in its place. See this community post for details. |
|
| redcap_module_project_enable($version, $project_id) | 9.0.0 | Triggered when a module gets enabled on a specific project. |
| redcap_module_project_delete_after($project_id, $action, $user_id) | 14.3.2 | BETA: This is a newer hooks that has some design concerns. Use it with caution. Allows custom actions to be performed after a delete action has been initiated, but before being redirected. This allows for close control of the delete operation on a project. The function is executed after project delete action has been initiated but, BEFORE redirected back to the My Projects page. The $action parameter will contain a string indicating the type of action performed. The possible values for $action are "prompt" (for a prompt), "prompt_undelete" (for an undelete), and "delete" (for deleting a project). |
| redcap_module_project_disable($version, $project_id) | 9.0.0 | Triggered when a module gets disabled on a specific project. |
| redcap_module_project_save_after($project_id, $msg_flag, $project_title, $user_id) | 14.3.2 | BETA: This is a newer hooks that has some design concerns. Use it with caution. Allows custom actions to be performed after a project has been saved from a newly created, copied, or modified project. This allows for close control of the create, copy, and modify operations on a project (e.g. capturing any values that were added to the form through the $_POST array). The function is executed after a project has been saved to the database, BEFORE a redirect to the ProjectSetup/index.php page. The $msg_flag parameter will contain a string indicating the type of project save that was performed. The possible values for $msg are "newproject" (for a new project), "copiedproject" (for a project copy), and "projectmodified" (for a modified project). |
| redcap_module_configure_button_display() | 9.0.0 | Triggered when each enabled module defined is rendered. Return null if you don't want to display the Configure button and true to display. |
| redcap_module_link_check_display($project_id, $link) | 9.0.0 | Triggered when each link defined in config.json is rendered, allowing link visibility to be controlled dynamically. This method also controls whether pages will load if their URL is accessed directly. Override this method and return null to prevent a given link from displaying, or modify and return the $link parameter as desired. The $link parameter is an array matching the link definition in config.json with an additional url value added. |
| redcap_module_save_configuration($project_id) | 9.0.0 | Triggered after a module configuration is saved. |
| redcap_module_import_page_top($project_id) | 9.0.0 | Triggered at the top of the Data Import Tool page. |
<?php
function redcap_module_system_enable($version) {
// Do stuff
}
function redcap_module_system_disable($version) {
// Do stuff
}