From f5d7f98cd47692b214e3b806911286854b0f7fcd Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Sun, 5 Jan 2020 22:51:15 -0500 Subject: [PATCH 1/8] Add 'REDCap Extension History lesson' --- docs/guide_for_admins_and_devs.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 64e79a7..9816c4a 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -7,3 +7,29 @@ title: REDCap External Module Development for REDCap Admins and Developers This guide is a non-technical guide for extending the features of your REDCap with a focus on developing new modules. It provides an introduction to external modules and guidance in creating a team and plan for developing modules for one’s own needs and the larger REDCap community. The audience for this guide is both REDCap Admins _and_ developers. It explains why REDCap modules are an effective means of extending REDCap. It explains how decisions made by Vanderbilt's REDCap teams and research aims shape the how module development should be managed. +If you actually want to _write_ a module, this guide is just the first step to understanding the work that needs to be done. After reading this material, developers and other apsiring module authors will want to read and do the exercises in [REDCap External Module Development for Developers](guide_for_devs/). + + +## REDCap Extension History lesson + +External Modules--referred to hereafter as simply _modules_--are neither the first nor the only method of extending REDCap. The first sanctioned method for extending REDCap was _plugins_. Plugins were introduced in REDCap 4.6.0 in 2011. In REDCap, a plugin is an entirely novel page in the REDCap web app. This new page was often presented in the left hand side bar via the Bookmark feature in REDCap. + +Hooks were introduced in May 2014 in REDCap 5.11.0 though that was just a rebranding of REDCap Extensions from REDCap 5.8.0, which, in turn, was a rebranding of Custom REDCap Functions from who knows when. Ignoring all that history, the role of a hoook is to allow an existing REDCap page to be modified without changing REDCap core code. A hook is a named function which--if it exists--will be called during a page load. Typically, the hook function will be called at the beginning of the page construction or the very end. Hook functions can be pure PHP, just enough PHP to load some novel Javascript, or a mixture of PHP and Javascript. + +Both hooks and functions are (were?) powerful ways to modify REDCap. Some plugin and hook code was useful enough that it was shared within the REDCap community and posted to the community web site, Box.com, or in Github. + +Yet in their original form, both hooks and plugins have issues. When they require configuration, it is generally difficult to manage. Some were written with configuration code embedded in the source code. To configure those, you had to have basic developer skills to change the lines of code that held the configuration details, then deploy the code. If the configuration details were wrong, talk to the developer again, get a fix, then redeploy the code. + +This embedded configuration made code sharing harder. If you wanted the new version of the hook code you had to apply your configuration code to the new code then deploy that. Even within your own systems, if your staging and production systems needed different configuration details you couldn't use the same code on both systems. + +Another configuration method was to store the configuration in a record in the redcap_log_event table. It's a little kludgy, but it works. Yet when an extension that uses log-event table method of configuration management fails, it's hard to debug and even harder to fix. + +Code that was only supposed to be applied to a few projects presented further challenges. The methods for managing a per-project deployment were in the hands of the develpper or system admin instead of the REDCap Admin. + +When hooks are working right, they work great, but a PHP error in a hook or plugin can be unforgiving. With PHP errors turned off, a production system displays nothing but an empty white screen if the code contains a PHP syntax error. A buggy plugin could be toxic to a REDCap system. Reverting the code of a buggy plugin or hook is as tedious as a deployment. + +Neither hooks nor plugins were well-labeled. There was no way for your REDCap system to tell you which extensions were deployed much less which _versions_ of those extensions were deployed. A particular bit of custom code might present its name or its version number clearly, but there was no convention where to present that information or system to present it. + +The licensing and distribution methods for hooks and plugins were quite challenging. Almost no hooks or plugins had a license of any kind. If there were bugs in an extension and you had a fix, it wasn't clear if you had the right to redistribute the fix because there was mo license. As to the distribution of plugins, most were posted on in the REDCap community. Yet some were distributed in Box while others were in repos on Github. You could look up many of the extensions in the REDCap community site, but that was not reliable. It was also hard to know if you had the latest code for the extension you found in the community. + +These challenges are why you should avoid using Plugins and Hooks whenever possible. Yet you probably never will have to use those extensions as the _concepts_ of hooks and plugins are part of REDCap Modules and most of the popular hook and plugins have been ported to modules. From a2628906174d0c2dc5b13d82a29f5c2f3dff8b11 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 6 Jan 2020 09:31:33 -0500 Subject: [PATCH 2/8] Fix typo in guide_for_admins_and_devs.md --- docs/guide_for_admins_and_devs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 9816c4a..8a4eca1 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -24,7 +24,7 @@ This embedded configuration made code sharing harder. If you wanted the new vers Another configuration method was to store the configuration in a record in the redcap_log_event table. It's a little kludgy, but it works. Yet when an extension that uses log-event table method of configuration management fails, it's hard to debug and even harder to fix. -Code that was only supposed to be applied to a few projects presented further challenges. The methods for managing a per-project deployment were in the hands of the develpper or system admin instead of the REDCap Admin. +Code that was only supposed to be applied to a few projects presented further challenges. The methods for managing a per-project deployment were in the hands of the developer or system admin instead of the REDCap Admin. When hooks are working right, they work great, but a PHP error in a hook or plugin can be unforgiving. With PHP errors turned off, a production system displays nothing but an empty white screen if the code contains a PHP syntax error. A buggy plugin could be toxic to a REDCap system. Reverting the code of a buggy plugin or hook is as tedious as a deployment. From a7c46a551953691a87d87a93b5cbdb2f514283bc Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 6 Jan 2020 13:39:41 -0500 Subject: [PATCH 3/8] Update docs/guide_for_admins_and_devs.md Co-Authored-By: Kyle Chesney --- docs/guide_for_admins_and_devs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 8a4eca1..8d262b1 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -30,6 +30,6 @@ When hooks are working right, they work great, but a PHP error in a hook or plug Neither hooks nor plugins were well-labeled. There was no way for your REDCap system to tell you which extensions were deployed much less which _versions_ of those extensions were deployed. A particular bit of custom code might present its name or its version number clearly, but there was no convention where to present that information or system to present it. -The licensing and distribution methods for hooks and plugins were quite challenging. Almost no hooks or plugins had a license of any kind. If there were bugs in an extension and you had a fix, it wasn't clear if you had the right to redistribute the fix because there was mo license. As to the distribution of plugins, most were posted on in the REDCap community. Yet some were distributed in Box while others were in repos on Github. You could look up many of the extensions in the REDCap community site, but that was not reliable. It was also hard to know if you had the latest code for the extension you found in the community. +The licensing and distribution methods for hooks and plugins were quite challenging. Almost no hooks or plugins had a license of any kind. If there were bugs in an extension and you had a fix, it wasn't clear if you had the right to redistribute the fix because there was no license. As to the distribution of plugins, most were posted on in the REDCap community. Yet some were distributed in Box while others were in repos on GitHub. You could look up many of the extensions in the REDCap community site, but that was not reliable. It was also hard to know if you had the latest code for the extension you found in the community. These challenges are why you should avoid using Plugins and Hooks whenever possible. Yet you probably never will have to use those extensions as the _concepts_ of hooks and plugins are part of REDCap Modules and most of the popular hook and plugins have been ported to modules. From 512071e80194aeebae34c3566017eefb7f13d845 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 6 Jan 2020 13:40:05 -0500 Subject: [PATCH 4/8] Update docs/guide_for_admins_and_devs.md Co-Authored-By: Kyle Chesney --- docs/guide_for_admins_and_devs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 8d262b1..16944c6 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -7,7 +7,7 @@ title: REDCap External Module Development for REDCap Admins and Developers This guide is a non-technical guide for extending the features of your REDCap with a focus on developing new modules. It provides an introduction to external modules and guidance in creating a team and plan for developing modules for one’s own needs and the larger REDCap community. The audience for this guide is both REDCap Admins _and_ developers. It explains why REDCap modules are an effective means of extending REDCap. It explains how decisions made by Vanderbilt's REDCap teams and research aims shape the how module development should be managed. -If you actually want to _write_ a module, this guide is just the first step to understanding the work that needs to be done. After reading this material, developers and other apsiring module authors will want to read and do the exercises in [REDCap External Module Development for Developers](guide_for_devs/). +If you actually want to _write_ a module, this guide is just the first step to understanding the work that needs to be done. After reading this material, developers and other aspiring module authors will want to read and do the exercises in [REDCap External Module Development for Developers](guide_for_devs/). ## REDCap Extension History lesson From 73a445efadcb08b0fac0af392a56fa3655b472da Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 6 Jan 2020 13:40:26 -0500 Subject: [PATCH 5/8] Update docs/guide_for_admins_and_devs.md Co-Authored-By: Kyle Chesney --- docs/guide_for_admins_and_devs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 16944c6..3540bcc 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -14,7 +14,7 @@ If you actually want to _write_ a module, this guide is just the first step to u External Modules--referred to hereafter as simply _modules_--are neither the first nor the only method of extending REDCap. The first sanctioned method for extending REDCap was _plugins_. Plugins were introduced in REDCap 4.6.0 in 2011. In REDCap, a plugin is an entirely novel page in the REDCap web app. This new page was often presented in the left hand side bar via the Bookmark feature in REDCap. -Hooks were introduced in May 2014 in REDCap 5.11.0 though that was just a rebranding of REDCap Extensions from REDCap 5.8.0, which, in turn, was a rebranding of Custom REDCap Functions from who knows when. Ignoring all that history, the role of a hoook is to allow an existing REDCap page to be modified without changing REDCap core code. A hook is a named function which--if it exists--will be called during a page load. Typically, the hook function will be called at the beginning of the page construction or the very end. Hook functions can be pure PHP, just enough PHP to load some novel Javascript, or a mixture of PHP and Javascript. +Hooks were introduced in May 2014 in REDCap 5.11.0 though that was just a rebranding of REDCap Extensions from REDCap 5.8.0, which, in turn, was a rebranding of Custom REDCap Functions from who knows when. Ignoring all that history, the role of a hook is to allow an existing REDCap page to be modified without changing REDCap core code. A hook is a named function which--if it exists--will be called during a page load. Typically, the hook function will be called at the beginning of the page construction or the very end. Hook functions can be pure PHP, just enough PHP to load some novel JavaScript, or a mixture of PHP and JavaScript. Both hooks and functions are (were?) powerful ways to modify REDCap. Some plugin and hook code was useful enough that it was shared within the REDCap community and posted to the community web site, Box.com, or in Github. From 2e148ff2b2f0dbe458976df45f329d9d05445259 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 6 Jan 2020 13:40:51 -0500 Subject: [PATCH 6/8] Update docs/guide_for_admins_and_devs.md Co-Authored-By: Kyle Chesney --- docs/guide_for_admins_and_devs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 3540bcc..d99f0e4 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -16,7 +16,7 @@ External Modules--referred to hereafter as simply _modules_--are neither the fir Hooks were introduced in May 2014 in REDCap 5.11.0 though that was just a rebranding of REDCap Extensions from REDCap 5.8.0, which, in turn, was a rebranding of Custom REDCap Functions from who knows when. Ignoring all that history, the role of a hook is to allow an existing REDCap page to be modified without changing REDCap core code. A hook is a named function which--if it exists--will be called during a page load. Typically, the hook function will be called at the beginning of the page construction or the very end. Hook functions can be pure PHP, just enough PHP to load some novel JavaScript, or a mixture of PHP and JavaScript. -Both hooks and functions are (were?) powerful ways to modify REDCap. Some plugin and hook code was useful enough that it was shared within the REDCap community and posted to the community web site, Box.com, or in Github. +Both hooks and functions are (were?) powerful ways to modify REDCap. Some plugin and hook code was useful enough that it was shared within the REDCap community and posted to the community web site, Box.com, or in GitHub. Yet in their original form, both hooks and plugins have issues. When they require configuration, it is generally difficult to manage. Some were written with configuration code embedded in the source code. To configure those, you had to have basic developer skills to change the lines of code that held the configuration details, then deploy the code. If the configuration details were wrong, talk to the developer again, get a fix, then redeploy the code. From f8deb608ef9215330e9e482c64feef7de0603274 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 6 Jan 2020 14:00:53 -0500 Subject: [PATCH 7/8] Fix content in 'REDCap Extension History lesson' --- docs/guide_for_admins_and_devs.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index d99f0e4..6cc7d3c 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -12,11 +12,15 @@ If you actually want to _write_ a module, this guide is just the first step to u ## REDCap Extension History lesson -External Modules--referred to hereafter as simply _modules_--are neither the first nor the only method of extending REDCap. The first sanctioned method for extending REDCap was _plugins_. Plugins were introduced in REDCap 4.6.0 in 2011. In REDCap, a plugin is an entirely novel page in the REDCap web app. This new page was often presented in the left hand side bar via the Bookmark feature in REDCap. +External Modules--referred to hereafter as simply _modules_--were introduced as a REDCap add-on in August of 2017 and formally released as part of REDCap 8.0.0 in November of 2017. Yet they are neither the first nor the only method of extending REDCap. -Hooks were introduced in May 2014 in REDCap 5.11.0 though that was just a rebranding of REDCap Extensions from REDCap 5.8.0, which, in turn, was a rebranding of Custom REDCap Functions from who knows when. Ignoring all that history, the role of a hook is to allow an existing REDCap page to be modified without changing REDCap core code. A hook is a named function which--if it exists--will be called during a page load. Typically, the hook function will be called at the beginning of the page construction or the very end. Hook functions can be pure PHP, just enough PHP to load some novel JavaScript, or a mixture of PHP and JavaScript. +The first sanctioned method for extending REDCap was _plugins_. Plugins were introduced in REDCap 4.6.0 in 2011. In REDCap, a plugin is an entirely novel page in the REDCap web app. This new page was often presented in the left hand side bar via the Bookmark feature in REDCap. -Both hooks and functions are (were?) powerful ways to modify REDCap. Some plugin and hook code was useful enough that it was shared within the REDCap community and posted to the community web site, Box.com, or in GitHub. +REDCap 5.11.0 introduced the _hook_ extension in May 2014, though that was just a rebranding of REDCap Extensions from REDCap 5.8.0, which, in turn, was a rebranding of Custom REDCap Functions from who knows when. Ignoring all that history, the role of a hook is to allow an existing REDCap page to be modified without changing REDCap core code. A hook is a named function which--if it exists--will be called during a page load. Typically, the hook function will be called at the beginning of the page construction or the very end. Hook functions can be pure PHP, just enough PHP to load some novel JavaScript, or a mixture of PHP and JavaScript. + +Hooks and plugins are relevant to modules because both concepts live on within modules. Their history is relevant as it influenced the module framework and Vanderbilt's rules used for developing modules. Their history also explains why they are on the way out as standalone extension methods. + +Both hooks and plugins are powerful ways to modify REDCap. Some plugin and hook code was useful enough that it was shared within the REDCap community and posted to the community web site, Box.com, or in GitHub. Yet in their original form, both hooks and plugins have issues. When they require configuration, it is generally difficult to manage. Some were written with configuration code embedded in the source code. To configure those, you had to have basic developer skills to change the lines of code that held the configuration details, then deploy the code. If the configuration details were wrong, talk to the developer again, get a fix, then redeploy the code. From d00efd02b88c36854376c5fab37bcbce8066b99b Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 6 Jan 2020 14:01:49 -0500 Subject: [PATCH 8/8] Remove trailing slashes form document names --- docs/guide_for_admins_and_devs.md | 2 +- docs/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 6cc7d3c..3e83e0a 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -7,7 +7,7 @@ title: REDCap External Module Development for REDCap Admins and Developers This guide is a non-technical guide for extending the features of your REDCap with a focus on developing new modules. It provides an introduction to external modules and guidance in creating a team and plan for developing modules for one’s own needs and the larger REDCap community. The audience for this guide is both REDCap Admins _and_ developers. It explains why REDCap modules are an effective means of extending REDCap. It explains how decisions made by Vanderbilt's REDCap teams and research aims shape the how module development should be managed. -If you actually want to _write_ a module, this guide is just the first step to understanding the work that needs to be done. After reading this material, developers and other aspiring module authors will want to read and do the exercises in [REDCap External Module Development for Developers](guide_for_devs/). +If you actually want to _write_ a module, this guide is just the first step to understanding the work that needs to be done. After reading this material, developers and other aspiring module authors will want to read and do the exercises in [REDCap External Module Development for Developers](guide_for_devs). ## REDCap Extension History lesson diff --git a/docs/index.md b/docs/index.md index bc962bd..67a96a0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,5 +7,5 @@ title: REDCap External Module Development Guide This site is a guide to the development of software extensions to Vanderbilt University's Research Electronic Data CAPture (REDCap) using REDCap's External Module framework. Added to REDCap in the Fall of 2018, the external module framework has proven to be an effective an popular way to change REDCap's behavior to meet the needs of specific sites and projects. This guide provides an introduction to external modules and guidance in creating a team and plan for developing modules for one's own needs and the larger REDCap community. -The audience for this guide is both REDCap Admins and software developers who would be writing the modules. The guide is split into a two sections to address the different audiences. The first section, [REDCap External Module Development for REDCap Admins and Developers](guide_for_admins_and_devs/), provides the background both audiences need to work together to create and share a module with the REDCap community. The second section, [REDCap External Module Development for Developers](guide_for_devs/), provides guidance to developers on how to write the module code, REDCap classes, and resources for module development. The developer's guide is primarily composed of a series of exercises to create simple modules that extend REDCap in different ways. +The audience for this guide is both REDCap Admins and software developers who would be writing the modules. The guide is split into a two sections to address the different audiences. The first section, [REDCap External Module Development for REDCap Admins and Developers](guide_for_admins_and_devs), provides the background both audiences need to work together to create and share a module with the REDCap community. The second section, [REDCap External Module Development for Developers](guide_for_devs), provides guidance to developers on how to write the module code, REDCap classes, and resources for module development. The developer's guide is primarily composed of a series of exercises to create simple modules that extend REDCap in different ways.