https://github.com/ctsit/extensible-redcap-hooks
Extensible REDCap Hooks
https://github.com/ctsit/extensible-redcap-hooks
deprecated redcap redcap-hooks
Last synced: about 2 months ago
JSON representation
Extensible REDCap Hooks
- Host: GitHub
- URL: https://github.com/ctsit/extensible-redcap-hooks
- Owner: ctsit
- License: other
- Created: 2017-01-10T21:37:13.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-08-24T12:49:07.000Z (almost 9 years ago)
- Last Synced: 2025-01-10T14:52:27.240Z (over 1 year ago)
- Topics: deprecated, redcap, redcap-hooks
- Language: PHP
- Size: 12.7 KB
- Stars: 1
- Watchers: 9
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Extensible REDCap Hooks - ARCHIVED
**This repository has been archived and is no longer actively maintained.**
This project was archived as of October 1, 2025. The project for which it was written is now over. There's no funding to provide further maintenance for other projects. Please don't hesitate to use this code in accordance with the license; however, the authors are unable to offer any additional support.
-----------
REDCap supports only one hooks file, specified under REDCap Control Center >
General Configuration > REDCap Hooks. By using the `redcap_hooks.php` file in
this folder, you will essentially be able to use multiple hooks. Furthermore,
hooks can be assigned to a specific project.
## Installation
1. Move these files to your REDCap server, making note of the full path to the
`redcap_hooks.php` file.
2. Open your browser and go to your REDCap Control Center.
3. Click "General Configuration".
4. Under "REDCap Hooks", enter the full path to the `redcap_hooks.php` file.
## Adding Hooks
Essentially `redcap_hooks.php` adds a layer of indirection that allows for
multiple implementations per hook. Each hook-function in that file looks for
actual hooks in other PHP files with the same name as the hook.
For example, if you wanted to add functionality when displaying a data entry
form, the hook is called `redcap_data_entry_form`. So, you would create a
`redcap_data_entry_form.php` file with your hook-function in it.
## Writing Hook-functions
To avoid name collisions, each hook should be implemented as an [Anonymous
Function](http://php.net/manual/en/functions.anonymous.php)–introduced in PHP
5.3–with the same parameters as the original hook.
For example, here is the entire contents of a `redcap_data_entry_form.php`
file:
alert("REDCap Hook Alert!");'
};
## Project-specific Hooks
If you wanted to have a hook enabled for a specific project, put your hook's
file under a folder named in the format `pid{$project_id}`, where
`{$project_id}` is the project's REDCap ID.
For example, if you wanted the aforementioned Data Entry hook enabled only for
Project #12, create `pid12/redcap_data_entry_form.php`.
## Additional Hooks
If you have more than one hook, you can create a folder named after the hook
and every PHP file under that folder will be assumed to be a hook file.
For example:
- `redcap_data_entry_form/print-disclaimer.php`
- `pid12/redcap_data_entry_form/00-alt-confirm-dialog-hook.php`
- `pid12/redcap_data_entry_form/01-other-hook.php`
- `pid12/redcap_data_entry_form/9-more-stuff.php`
## Summary of File Naming Convention
Hooks are searched for in four places, all relative to the folder in which
`redcap_hooks.php` resides:
1. Global hook: `$hook_name.php`
2. Additional global hooks: `$hook_name/*.php`
3. Project-specific hook: `pid{$project_id}/$hook_name.php`
4. Additional project-specific hooks: `pid{$project_id}/$hook_name/*.php`
"Global" hooks are not specific to a project and will run for all projects.
_Caveat:_ PHP's `__DIR__` is used, so take care if using symbolic links.
## Supported Hooks
Every hook except `redcap_custom_verify_username` is supported.
Since `redcap_custom_verify_username` has a non-void return type it has to be
implemented only if needed and directly in `redcap_hooks.php` as per the REDCap
documentation.
## Logging
To activate logging on a specific hook_function, add a `TRUE` as the third
parameter of the call to `redcap_hooks_find` within that hook function. E.g., turn
$hook_files = redcap_hooks_find('redcap_data_entry_form_top', $project_id);
into
$hook_files = redcap_hooks_find('redcap_data_entry_form_top', $project_id, TRUE);
Hook logging output will be written to `/tmp/hook_events.log` This can be changed by editing
the `redcap_hooks_find` function.
## Contributors
- Taeber Rapczak, University of Florida
- Philip Chase, University of Florida
Thank you to Andrew Martin (Stanford University) for his original work on
custom REDCap Hooks.
## License
Copyright 2017, University of Florida; licensed under the Apache License,
Version 2.0. See the [LICENSE](LICENSE) file for the full text.