Why would someone build a REDCap plugin?

A REDCap plugin can be built for a variety of reasons. It may be to build a custom PHP page that simply piggybacks REDCap's authentication (if your plugin's users would also be REDCap users), thus preventing one from having to construct their own web application's method of authentication from scratch. Also, it could be used just for connecting to and querying REDCap's database tables in a quick and easy fashion. Of course, the major advantage of having a REDCap plugin is that you can construct it such that it can be utilized in REDCap as if it were an official page within REDCap itself. Such could be accomplished in tandem with the Project Bookmarks functionality, which allows you to create a link to your plugin on a REDCap project's left-hand menu to allow easy navigation between that project and your plugin, thus making creating seamless navigation to and from your plugin.

How are plugins accessed in REDCap?

Since plugins have their own specific URL where they can be accessed, a user must know the exact URL in order to navigate to a plugin, or the user may use one of the two types of configurable links in REDCap to invoke a plugin (seen below):

• Project Bookmarks
• Custom Application Links

Custom Application Links are system-level, that is, they apply to all projects. They can be set up on the Custom Application Links page in the Control Center. Once defined, they will appear for all projects in the left hand menu at the bottom of the "Applications" panel.

Project Bookmarks are project-level, applying only to the project in which they are defined. They can be set up by clicking the button in the "Set up project bookmarks" section of the Project Setup page in a given REDCap project. Once defined, these will appear only for that single project in the left hand menu in the "Project Bookmarks" panel.

Apart from these differences, Custom Application Links and Project Bookmarks operate identically.

Who can build a REDCap plugin?

In order to build a plugin that interfaces with REDCap properly, one must have direct access to the file system on the web server that hosts REDCap at your local institution. This is required because your plugin file(s) will need to be hosted on the REDCap web server. A person with such high level access would likely be a REDCap administrator (i.e. super user) or a web developer on their team. Such a person would NOT include typical REDCap end-users. Building a plugin requires knowledge about creating and programming web applications, specifically knowing PHP, which is the scripting language in which REDCap is programmed. If you don't know much PHP at all, you can probably still get by by utilizing parts of the examples below if your plugin is mostly just HTMl and uses PHP very little. If you wish to query REDCap's database tables, you will need to know SQL in order to write queries. If the plugin is meant to output a web page in the user's web browser, then knowing HTML is necessary (and perhaps some Javascript and CSS if you want to get fancy).

Who can use a REDCap plugin?

Answer: Anyone you allow to use it. Since you are creating your own custom plugin, you control how it is used and who can use it. You may limit access to the plugin to only specific REDCap projects and/or to only specific REDCap users, or conversely, you may make it fully available to all projects and users in REDCap in your REDCap installation. It's up to you. You are the architect.

How does one call the redcap_connect.php file?

In order for your plugin to connect to REDCap's framework, the plugin must call the redcap_connect.php file. You can call redcap_connect.php by doing a "require_once" (or "include_once") of the file (see the examples at the bottom of this page). When doing that, there are 3 ways to successfully include the file:

1. Use a full path (e.g., for Linux: require_once "/home/username/www/redcap/redcap_connect.php"; for Windows: require_once "C:\\xampp\\htdocs\\redcap\\redcap_connect.php";).
2. Use a relative path (e.g., if in the same directory: require_once "redcap_connect.php"; if one subdirectory down: require_once "../redcap_connect.php"; if three subdirectories down: require_once "../../../redcap_connect.php";).
3. Add your main "redcap" directory to the PHP include_path in PHP.INI, thus you only ever have to specify require_once "redcap_connect.php"; regardless of where your plugin is located on the web server.

NOTE: The redcap_connect.php file should be located in the main REDCap directory where database.php is located. If redcap_connect.php is not in that location, you may obtain the file from the install zip of the latest version of REDCap, and then place the redcap_connect.php file the main REDCap directory on your web server.

Where should my plugin file(s) be located on the REDCap web server?

Your plugin file(s) can actually be located anywhere under your web server's web root (i.e. any directory accessible via the web). The most common place to put a plugin file is in a directory named "plugins" directly under the main "redcap" folder on the web server.

What is the difference between project-level and system-level plugins?

REDCap classifies its pages as falling into two basic categories: system-level pages and project-level pages. Project-level pages are any pages in REDCap that are used when accessing a specific REDCap project (e.g., Data Export Tool, user-defined data entry forms, User Rights). At the most basic level, a project-level page can be defined as any page containing "pid", which is the project_id, in the URL query string (e.g., https://YOURSERVERNAME/redcap_v4.5.0/index.php?pid=2). Conversely, system-level pages are pages that are not project-centric (i.e. anything that's not a project-level page), such as the My Projects page, the Help & FAQ page, or any Control Center pages. When using a REDCap plugin, if "pid" is not found in the query string of the URL, then it treats the plugin as a system-level page, thus utilizing all system-level values, such as authentication and so forth. And if "pid" is found in the query string, then it treats the plugin as a project-level page, thus employing that specific project's authentication (which may be different from the system-level authentication method used), as well as adding the project's project-level PHP variables to PHP's global scope. For project-level plugin pages, REDCap will institute the project-level user rights also. So if the user accessing the plugin is not a user on that particular project, then they will not be able to access the plugin (unless they are a super user since super users have access to all projects).

If you wish to display REDCap's official page headers and footers that are normally seen in the application, thus giving your plugin the appearance of being a traditional page within REDCap, then the header/footer are called via PHP in different ways for the project-level pages vs. the system-level pages. Calling a header or footer only takes 1 or 2 lines of PHP code in your plugin. Example 3 below shows how to call headers/footers for system-level pages, whereas Example 4 shows how to call them for project-level pages. If someone building a plugin mistakenly tries to display a project-level header or footer on a system-level page, then the header and footer will not display correctly on the page and will provide a warning message explaining why the header/footer cannot be displayed properly. However, project-level plugins CAN display system-level page headers/footers.

Is it possible to disable REDCap's authentication but still utilize other REDCap resources?

Answer: Yes. By default, redcap_connect.php will enforce REDCap's authentication, thus prompting a REDCap login screen and maintaining your session as REDCap normally does. But you may disable authentication if you wish. To disable REDCap's authentication (i.e. prevent the login page from displaying, thus making the web page completely public and viewable to anyone), all you need to do is add the following PHP code before you include the redcap_connect.php file: define("NOAUTH", true);. Below is an example of this. NOTE: If authentication is disabled, then REDCap's user-related PHP constants USERID and SUPER_USER will not be defined.

<?php
// Disable REDCap's authentication
define("NOAUTH", true);

// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

## Your custom PHP code goes here.

How to limit plugin access to specific projects and/or specific users

By default, a plugin will be fully accessible for all REDCap users and all REDCap projects. (If authentication is manually disabled, then it will be accessible to the world - i.e. anyone who can reach that URL.) It is likely that one may wish to lock down a plugin so that only specific projects can access it or perhaps specific users (or specific users within a specific project). This can be done by utilizing two different methods built into REDCap: REDCap::allowProjects() and REDCap::allowUsers(). NOTE: REDCap::allowProjects() is only to be used for project-level plugins (it will be ignored if called in a system-level plugin). You will want to probably place these functions immediately after including the redcap_connect.php file (see examples below). You may use one, both, or neither of the functions together in a plugin. For both functions, you may pass in the parameters either as an array of values OR as separate multiple parameters to the function. For REDCap::allowProjects(), you will need to pass in the project_id's of the projects that you wish to be able to access this plugin (all other projects will not be able to access it). For REDCap::allowUsers, you will need to pass in the REDCap usernames of the users that you wish to be able to access it (all other users will not be able to access it). If a user tries to access a plugin when they are not listed in the REDCap::allowUsers() method (or if someone in a project tries to access it when the project's project_id is not listed in the REDCap::allowProjects() method), then the user will receive a red error box saying that they cannot access the page because they do not have proper access rights. This error also halts the rendering of the rest of the page.

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

// Limit this plugin only to project_id's 3, 12, and 45
$projects = array(3, 12, 45);
REDCap::allowProjects($projects);

## Your custom PHP code goes here.

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

// Limit this plugin only to users 'taylorr4' and 'harrispa' in projects with project_id 56 and 112
REDCap::allowProjects(56, 112);
REDCap::allowUsers('taylorr4', 'harrispa');

## Your custom PHP code goes here.

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

// Limit this plugin only to users 'taylorr4' and 'harrispa'
$users = array('taylorr4', 'harrispa');
REDCap::allowUsers($users);

## Your custom PHP code goes here.

How does one begin creating a REDCap plugin?

As of REDCap version 5.5.0, the installation package of REDCap comes pre-loaded with the redcap_connect.php file and some example plugin files that are simple examples of how one might create a plugin. Aside from doing the initial "require_once" (or "include_once") of the redcap_connect.php file, the sky is the limit for what you can do next. For your convenience, REDCap has a PHP function called redcap_info() (similar to phpinfo()) that can be called from anywhere within a REDCap page or plugin page. Calling the redcap_info() function will automatically render a web page (when viewing the script in a web browser) that will display a table listing all PHP constants and variables that have been pre-defined by REDCap and are thus available for utilization in a plugin. Thus it gives you a head start by letting you know what resources are available that you may utilize in your plugin code. You can see the output of redcap_info() by clicking its link on the left-hand menu on this page. Also seen below are other basic examples of plugins that you may peruse for getting an idea of how to begin building your own.

What is the preferred method in a plugin for querying REDCap's database tables?

It is preferred that you utilize the MySQLi extension when making calls to the database. It is also acceptable to utilize PEAR DB or PDO (if your web server supports it). Please note that as of 01/14/2013, the redcap_connect.zip file (which can be downloaded at the top of the page if you do not have it) also automatically performs a MySQLi connection in addition to the existing MySQL connection, in which the database connection link is a global variable named $conn that one may utilize in your plugin code. You may use the MySQL extension (i.e. mysql_* functions) in plugins, but please keep in mind that the MySQL extension is deprecated in PHP 5.5. So it is recommended that you utilize MySQLi instead, although both the MySQL and MySQLi extensions can be utilized in plugins if using the latest REDCap Connect file that includes the MySQLi auto-connection (or if you make your own independent MySQLi database connection in your plugin).

Can I share my plugin with other REDCap partners?

Yes, we highly encourage plugin developers to share their plugins with other REDCap partners when applicable. There is a Plugin Library page on the consortium community website where anyone with access can upload their plugin to share. And as a plugin developer, you may also download any of the plugins that have already been uploaded and shared on that page. If you do not have access to the consortium community website, then someone from your institution most likely does, in which case they can request that you be given access by filling out the Request for Access to REDCap Consortium Support Tools survey for you.

Plugin Examples

The "redcap_connect.php" file and plugin example files can be obtained from the install zip of the latest version of REDCap if you do not yet have them.

** NOTE: All the examples below assume that the plugin page exists in a directory below the redcap_connect.php file. **

Example 1: Simple plugin template (with no REDCap header/footer)

This will first provide a login screen to log in to REDCap. Once logged in, it will display a blank page.

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

## Your custom PHP code goes here. You may use any constants/variables listed in redcap_info().

## Your HTML page content goes here

Example 2: Plugin page that only displays the redcap_info() table

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

// Display table of REDCap variables, constants, and settings - similar to phpinfo()
redcap_info();

Example 3: Simple plugin template displaying REDCap's system-level page header/footer

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

## Your custom PHP code goes here. You may use any constants/variables listed in redcap_info().

// OPTIONAL: Display the header
$HtmlPage = new HtmlPage();
$HtmlPage->PrintHeaderExt();

## Your HTML page content goes here

// OPTIONAL: Display the footer
$HtmlPage->PrintFooterExt();

Example 4: Simple plugin template displaying REDCap's project-level page header/footer

This plugin page assumes that "pid" (i.e. the project_id) exists in the URL query string. NOTE: If someone building a plugin mistakenly tries to display a project-level header or footer on a system-level page, then the header and footer will not display correctly on the page and will provide a warning message explaining why the header/footer cannot be displayed properly. However, project-level plugins CAN display system-level page headers/footers.

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

## Your custom PHP code goes here. You may use any constants/variables listed in redcap_info().

// OPTIONAL: Display the project header
require_once APP_PATH_DOCROOT . 'ProjectGeneral/header.php';

## Your HTML page content goes here

// OPTIONAL: Display the project footer
require_once APP_PATH_DOCROOT . 'ProjectGeneral/footer.php';

Example 5: Plugin that queries the REDCap database

<?php
// Call the REDCap Connect file in the main "redcap" directory
require_once "../redcap_connect.php";

// Query the redcap_data table using the MySQLi connection $conn
$query = "select * from redcap_data where project_id = $project_id";
$result = mysqli_query($conn, $query);
while ($row = mysqli_fetch_assoc($result)) {
    // Do something with this row from redcap_data
}