From 440c50805af8d448289731b68727cee36b68cb4d Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Thu, 19 Dec 2019 15:37:18 -0500 Subject: [PATCH 01/77] add basic hello world example --- exercises/README.md | 7 ++ .../hello_world_v0.0.0/ExternalModule.php | 14 ++++ exercises/hello_world_v0.0.0/README.md | 4 + exercises/hello_world_v0.0.0/config.json | 81 +++++++++++++++++++ .../pages/control_center_custom_page.php | 11 +++ .../pages/project_custom_page.php | 11 +++ 6 files changed, 128 insertions(+) create mode 100644 exercises/README.md create mode 100644 exercises/hello_world_v0.0.0/ExternalModule.php create mode 100644 exercises/hello_world_v0.0.0/README.md create mode 100644 exercises/hello_world_v0.0.0/config.json create mode 100644 exercises/hello_world_v0.0.0/pages/control_center_custom_page.php create mode 100644 exercises/hello_world_v0.0.0/pages/project_custom_page.php diff --git a/exercises/README.md b/exercises/README.md new file mode 100644 index 0000000..a1e0d0a --- /dev/null +++ b/exercises/README.md @@ -0,0 +1,7 @@ +# External Module Development Exercises + +This directory contains test modules to use as a guide for module development. The majority of them are missing essential functionality, the regions where you need to introduce this functionality are cordoned off with comments. +You should copy the contents of this directory to the `modules` directory or your REDCap container (or you may mount them as a volume). + +## Hello World +This is a "complete" module intended to be used to make sure your development pipeline is set up properly. diff --git a/exercises/hello_world_v0.0.0/ExternalModule.php b/exercises/hello_world_v0.0.0/ExternalModule.php new file mode 100644 index 0000000..146fecb --- /dev/null +++ b/exercises/hello_world_v0.0.0/ExternalModule.php @@ -0,0 +1,14 @@ + APP_PATH_IMAGES . 'bell.png']) . ' ' . REDCap::escapeHtml('Control Center Page'); +echo RCView::h4([], $title); +echo 'Hello World!!'; + +require_once APP_PATH_DOCROOT . 'ControlCenter/footer.php'; diff --git a/exercises/hello_world_v0.0.0/pages/project_custom_page.php b/exercises/hello_world_v0.0.0/pages/project_custom_page.php new file mode 100644 index 0000000..fadf247 --- /dev/null +++ b/exercises/hello_world_v0.0.0/pages/project_custom_page.php @@ -0,0 +1,11 @@ + APP_PATH_IMAGES . 'bell.png']) . ' ' . REDCap::escapeHtml('Control Center Page'); +echo RCView::h4([], $title); +echo 'Hello World!!'; + +require_once APP_PATH_DOCROOT . 'ProjectGeneral/footer.php'; From b8c9dc3011eef64c7d48fbe7edcccafe1ea82f0f Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Mon, 6 Jan 2020 15:41:35 -0500 Subject: [PATCH 02/77] update hello world module --- exercises/hello_world_v0.0.0/README.md | 5 +++-- exercises/hello_world_v0.0.0/config.json | 14 +++++++------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/exercises/hello_world_v0.0.0/README.md b/exercises/hello_world_v0.0.0/README.md index 3521feb..5dc70a6 100644 --- a/exercises/hello_world_v0.0.0/README.md +++ b/exercises/hello_world_v0.0.0/README.md @@ -1,4 +1,5 @@ # Hello World -Provides plugin pages in the Projects and in the Control Center that say "Hello, world". -Displays "Hello world! I am a message produced by a hook!" at the top of project pages. +Provides a page that says "Hello, world" in the control center and on projects. + +Shows admin view of a handful of configuration options. diff --git a/exercises/hello_world_v0.0.0/config.json b/exercises/hello_world_v0.0.0/config.json index cf18d89..3e7effc 100644 --- a/exercises/hello_world_v0.0.0/config.json +++ b/exercises/hello_world_v0.0.0/config.json @@ -8,13 +8,13 @@ ], "authors": [ { - "name": "Tiago Bember", - "email": "tbembersimeao@ufl.edu", + "name": "Kyle Chesney", + "email": "kyle.chesney@ufl.edu", "institution": "University of Florida - CTSI" }, { - "name": "Kyle Chesney", - "email": "kyle.chesney@ufl.edu", + "name": "Tiago Bember", + "email": "tbembersimeao@ufl.edu", "institution": "University of Florida - CTSI" } ], @@ -49,7 +49,7 @@ { "name": "Select system", "key": "dummy_select_system", - "type": "dropdown", + "type": "radio", "choices": [ { "value": "c", @@ -66,14 +66,14 @@ "project": [ { "name": "Hello Project", - "icon": "", + "icon": "fas globe", "url": "pages/project_custom_page.php" } ], "control-center": [ { "name": "Hello Admin", - "icon": "", + "icon": "fas fa-globe", "url": "pages/control_center_custom_page.php" } ] From 608a2e90dad5b9960acbdf62a0443c995ba92bbd Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Mon, 6 Jan 2020 15:42:16 -0500 Subject: [PATCH 03/77] add README to exercises page, will be moved to Jekyll site --- exercises/README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/exercises/README.md b/exercises/README.md index a1e0d0a..a4076c8 100644 --- a/exercises/README.md +++ b/exercises/README.md @@ -1,7 +1,24 @@ # External Module Development Exercises This directory contains test modules to use as a guide for module development. The majority of them are missing essential functionality, the regions where you need to introduce this functionality are cordoned off with comments. -You should copy the contents of this directory to the `modules` directory or your REDCap container (or you may mount them as a volume). -## Hello World +## Preface + +### Reference Materials +You will likely find it helpful to keep Vanderbilt's [official External Module documentation](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md) available while completing these exercises; this document will link relevant sections for review. + +### Setting Up Your Environment +Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). +You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using a [Docker environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. +Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. + +## Modules + +### Hello World This is a "complete" module intended to be used to make sure your development pipeline is set up properly. + +Read the section on [module requirements](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#module-requirement) until the section on hooks. + +### Hello Hook + +Read [the official documentation on calling hooks](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#how-to-call-redcap-hooks). From 4c71653c0cd6add6b2785f63fc9ac1e11f2f3878 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 7 Jan 2020 13:30:56 -0500 Subject: [PATCH 04/77] Update exercises/README and mirror it into docs --- docs/exercises.md | 29 +++++++++++++++++++++++++++++ docs/guide_for_devs.md | 4 ++++ exercises/README.md | 8 ++++---- 3 files changed, 37 insertions(+), 4 deletions(-) create mode 100644 docs/exercises.md diff --git a/docs/exercises.md b/docs/exercises.md new file mode 100644 index 0000000..796fe8f --- /dev/null +++ b/docs/exercises.md @@ -0,0 +1,29 @@ +--- +layout: default +title: External Module Development Exercises +--- + +# External Module Development Exercises + +The External Module Development Guide includes a set of [development exercises](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. + +## Preface + +### Reference Materials +You will likely find it helpful to keep Vanderbilt's [official External Module documentation](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md) available while completing these exercises; this document will link relevant sections for review. + +### Setting Up Your Environment +Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using Andy Martin's [redcap-docker-compose environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. + +## Modules + +All of module development exercises reside in the Git repo that houses this document at [https://github.com/ctsit/redcap_external_module_development_guide/exercises/](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) + +### Hello World +This is a "complete" module intended to be used to make sure your development pipeline is set up properly. + +Read the section on [module requirements](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#module-requirement) until the section on hooks. + +### Hello Hook + +Read [the official documentation on calling hooks](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#how-to-call-redcap-hooks). diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index 8776153..0768164 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -6,3 +6,7 @@ title: REDCap External Module Development for Developers # REDCap External Module Development for Developers This guide provides the technical background developers need to write and test module code. It describes the REDCap classes and resources that simplify module development. This guide is primarily composed of a series of exercises to create simple modules that extend REDCap in different ways. + +## Exercises + +The exercises can be found at [exercises](./exercises) diff --git a/exercises/README.md b/exercises/README.md index a4076c8..5a9b30d 100644 --- a/exercises/README.md +++ b/exercises/README.md @@ -1,6 +1,6 @@ # External Module Development Exercises -This directory contains test modules to use as a guide for module development. The majority of them are missing essential functionality, the regions where you need to introduce this functionality are cordoned off with comments. +The External Module Development Guide includes a set of [development exercises](./exercises/) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. ## Preface @@ -8,12 +8,12 @@ This directory contains test modules to use as a guide for module development. T You will likely find it helpful to keep Vanderbilt's [official External Module documentation](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md) available while completing these exercises; this document will link relevant sections for review. ### Setting Up Your Environment -Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). -You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using a [Docker environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. -Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. +Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using Andy Martin's [redcap-docker-compose environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. ## Modules +All of module development exercises reside in the Git repo that houses this document at [`https://github.com/ctsit/redcap_external_module_development_guide/exercises/`](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) + ### Hello World This is a "complete" module intended to be used to make sure your development pipeline is set up properly. From 1d96240f6389ce49d94575aa2f45b68353ec16f2 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 13 Jan 2020 00:47:11 -0500 Subject: [PATCH 05/77] Move developer's resources into docs/guide_for_devs.md and reduce duplication --- docs/exercises.md | 29 ---------------------------- docs/guide_for_devs.md | 43 +++++++++++++++++++++++++++++++++++++++--- exercises/README.md | 7 ++----- 3 files changed, 42 insertions(+), 37 deletions(-) delete mode 100644 docs/exercises.md diff --git a/docs/exercises.md b/docs/exercises.md deleted file mode 100644 index 796fe8f..0000000 --- a/docs/exercises.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: default -title: External Module Development Exercises ---- - -# External Module Development Exercises - -The External Module Development Guide includes a set of [development exercises](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. - -## Preface - -### Reference Materials -You will likely find it helpful to keep Vanderbilt's [official External Module documentation](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md) available while completing these exercises; this document will link relevant sections for review. - -### Setting Up Your Environment -Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using Andy Martin's [redcap-docker-compose environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. - -## Modules - -All of module development exercises reside in the Git repo that houses this document at [https://github.com/ctsit/redcap_external_module_development_guide/exercises/](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) - -### Hello World -This is a "complete" module intended to be used to make sure your development pipeline is set up properly. - -Read the section on [module requirements](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#module-requirement) until the section on hooks. - -### Hello Hook - -Read [the official documentation on calling hooks](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#how-to-call-redcap-hooks). diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index 0768164..d8a7da6 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -5,8 +5,45 @@ title: REDCap External Module Development for Developers # REDCap External Module Development for Developers -This guide provides the technical background developers need to write and test module code. It describes the REDCap classes and resources that simplify module development. This guide is primarily composed of a series of exercises to create simple modules that extend REDCap in different ways. +This guide provides the technical background developers need to write and test module code. It describes the REDCap classes and resources that simplify module development. This guide has recommendations for reference materials and tools to aid in module development and a series of exercises to create simple modules that extend REDCap in different ways. -## Exercises +## Reference Materials -The exercises can be found at [exercises](./exercises) +### REDCap Training Videos + +It's essential that you understand how to use REDCap before trying to develop modules for it. Vanderbilt provides a series of videos that provide basic training in how to use REDCap to create and administer instruments and surveys. See [https://projectredcap.org/resources/videos/](https://projectredcap.org/resources/videos/) + +The University of Colorado Denver has created a series of videos that address more advanced topics. You can access all of those videos at their [Youtube Playlist](https://www.youtube.com/playlist?list=PLrnf34ZtZ9FpHcZyZuNnNFZ9cEbhijNGf). + + +### Vanderbilt's External Module Documentation + +You will likely find it helpful to keep Vanderbilt's [official External Module documentation](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md) available while completing these exercises; this document will link relevant sections for review. + + +### REDCap Repo + +Vanderbilt publishes modules submitted by the REDCap Community in the [REDCap Repo](https://redcap.vanderbilt.edu/consortium/modules/index.php). The source code for each of these modules is accessible in Github and linked from the entries in the REDCap Repo. These modules provide fully functional code examples. As each module in the REDCap Repo is required to have an open source license, their code can be used in other modules. + + +### Github + +Beyond those in the REDCap Repo, Github.com is commonly used by developers in the REDCap community to host and share modules. Many of these modules are tagged with the topic 'redcap-external-module' and can be located with a [Github topic search](https://github.com/search?q=topic%3Aredcap-external-module&type=Repositories) + + +## Setting Up Your Environment +Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using Andy Martin's [redcap-docker-compose environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. + + +## External Module Development Exercises + +The External Module Development Guide includes a set of [development exercises](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. + +### Hello World +This is a "complete" module intended to be used to make sure your development pipeline is set up properly. + +Read the section on [module requirements](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#module-requirement) until the section on hooks. + +### Hello Hook + +Read [the official documentation on calling hooks](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#how-to-call-redcap-hooks). diff --git a/exercises/README.md b/exercises/README.md index 5a9b30d..ff6ed1f 100644 --- a/exercises/README.md +++ b/exercises/README.md @@ -1,14 +1,11 @@ # External Module Development Exercises -The External Module Development Guide includes a set of [development exercises](./exercises/) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. +The External Module Development Guide includes a set of [development exercises](./) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. ## Preface -### Reference Materials -You will likely find it helpful to keep Vanderbilt's [official External Module documentation](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md) available while completing these exercises; this document will link relevant sections for review. +For guidance in developing modules and resources for completing these exercises, see [REDCap External Module Development Guide](https://ctsit.github.io/redcap_external_module_development_guide/). -### Setting Up Your Environment -Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using Andy Martin's [redcap-docker-compose environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. ## Modules From 4b5c48a5cf323423b1b0b2de4f1915577824707b Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 13 Jan 2020 14:29:29 -0500 Subject: [PATCH 06/77] Update docs/guide_for_devs.md Kyle really wants a line break here. Co-Authored-By: Kyle Chesney --- docs/guide_for_devs.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index d8a7da6..defabfd 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -32,7 +32,8 @@ Beyond those in the REDCap Repo, Github.com is commonly used by developers in th ## Setting Up Your Environment -Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using Andy Martin's [redcap-docker-compose environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. +Read the section of the official documentation on [naming a module](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#naming-a-module). You should copy the contents of this directory to the `modules` directory of your REDCap instance. Assuming you are using Andy Martin's [redcap-docker-compose environment](https://github.com/123andy/redcap-docker-compose), the modules directory is located at `www/modules/`. +Please note that - with the exception of **Hello World** - you will need to mark the [semantic version](https://semver.org/) of each module - in short, you will need to append `_v0.0.0` to each directory - for it to be recognized by REDCap. These are intentionally left off to simulate having just `git clone`d a module from a public repository. Public repositories should _not_ have semantic versions in their titles. REDCap uses the directory name to determine module versions, each version will have its own directory, you should use `git tag`s and releases. ## External Module Development Exercises From a2c56200959ffb444f1a0263c65a804244bbbc81 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Sun, 19 Jan 2020 08:13:54 -0500 Subject: [PATCH 07/77] Fix tense errors and other typos in 'REDCap Extension History lesson' --- docs/guide_for_admins_and_devs.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 3e83e0a..8d1d35c 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -22,18 +22,18 @@ Hooks and plugins are relevant to modules because both concepts live on within m 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. +Yet in their original form, both hooks and plugins have issues. When they require configuration, it was 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--or a developer--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, ask them to make a fix, redeploy the code, and iterate that process until the configuration is correct. 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. +Another configuration method was to store the configuration in a record in the redcap_log_event table. It's a little kludgy, but it worked. Yet when an extension that used log-event table method of configuration management failed, it was 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 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. +When hooks worked right, they work great, but a PHP error in a hook or plugin can be unforgiving. With _PHP errors_ configuration option 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 was as tedious as the 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 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. +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 almost never a license. As to the distribution of plugins, most were posted 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. +These challenges are why you should avoid using Plugins and Hooks whenever possible. Yet you probably never will have to use those extensions because 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 3e1eeeb192c0997843c716e7b4a8109a922d1403 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Sun, 19 Jan 2020 10:42:51 -0500 Subject: [PATCH 08/77] Add sections to guide_for_admins_and_devs.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add 'What is “right” about modules?' Add 'REDCap Repo' --- docs/guide_for_admins_and_devs.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 8d1d35c..b6d2dfd 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -37,3 +37,24 @@ Neither hooks nor plugins were well-labeled. There was no way for your REDCap sy 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 almost never a license. As to the distribution of plugins, most were posted 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 because the _concepts_ of hooks and plugins are part of REDCap Modules and most of the popular hook and plugins have been ported to modules. + + +## What is “right” about modules? + +All of the bad features of the older REDCap extension methods lead us to what modules get right. Modules can be located, downloaded, enabled and configured through the REDCap GUI by a REDCap Admin. The External Module Framework allows projects to be enabled and configured on a per-project basis. The list of enabled modules is visible in the REDCap interface. They can be disabled as easily as they were enabled. + +The EM Framework requires modules have versions numbers when deployed. The version numbers integrate into the module upgrade features of the Framework. The REDCap Admin can see what version number is enabled, what versions have been downloaded to the server and what versions are ready to be enabled. The upgrade is simple. Should the new version prove flawed, the REDCap Admin can revert to the old version just as easily. + +The EM framework can detect the some of the more egreious coding errors, prevent the code from running, and disable the module that caused the problem. This lets the REDCap server continue normal function. + +These features are possible because the External Module Framework provides an infrastructure for software extension management. The EM Framework was designed to address the many management issues software extensions can create. It provides the rules for enabling, disabling, configuring, upgrading, downgrading, testing, and much more. It provides the interfaces the REDCap Admin sees. It defines rules modules--and their developers--must follow to integrate into those interfaces. + +## REDCap Repo + +Yet the EM Framework does not stand alone. Many of the features it provides are backed by the _REDCap Repo_. The REDCap Repo is a public collection of vetted REDCap modules maintained by the Vanderbilt UMC REDCap team. These modules have been submitted by the members of the REDCap community to be sharing within the community. VUMC reviews module submissions and publishes those that pass review in the REDCap Repo. + +As of January 2020, the repo contains 133 published modules. This large and growing collection is the database the EM Framework queries for module location and download. It allows the EM Framework to locate module upgrades suitable for a REDCap version and deliver them quickly and easily to the REDCap server. + +The vetting process performed by the VUMC REDCap team adds value to the modules in the REDCap Repo. The review process covers the basics but also addresses some esoteric and import details. Most important for the immediate need, the module must _work_. It must enable without errors, have a meaningful title and description, and do what it claims to do. The source code for the module must be published for public review in a software repository at [GitHub.com](https://github.com) and it must have an [open source software license](https://en.wikipedia.org/wiki/Open-source_license). The software must embrace coding styles that will make it reasonably easy to support as REDCap evolves. The software should also embrace REDCap's conventions for data access and data update where practicable. The module should follow EM Framework and software industry conventions for describing its software dependencies. The module should follow REDCap and software industry conventions for securing access to data and software features, sanitizing input, and resisting attack. The full details of the current review guidelines can be found at [External Modules: Module Review Guidelines](https://redcap.vanderbilt.edu/consortium/modules/external_modules_review_guidelines.pdf) + +The VUMC team's vetting process should never be considered a guarantee of quality, but it definitely _increases_ and _enables_ quality. The guidelines have specific details software developers can follow to improve the quality of their product. The guidelines also protect a module user's ability and right to do their own code review, provide feedback, make improvements, and publish those improvements. From 0feec97a2a0261b365dfecbe3e1ac6f9d995b953 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 20 Jan 2020 17:03:12 -0500 Subject: [PATCH 09/77] Add 'Where to find modules' to guide_for_admins_and_devs.md --- docs/guide_for_admins_and_devs.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index b6d2dfd..6029c8f 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -58,3 +58,21 @@ As of January 2020, the repo contains 133 published modules. This large and grow The vetting process performed by the VUMC REDCap team adds value to the modules in the REDCap Repo. The review process covers the basics but also addresses some esoteric and import details. Most important for the immediate need, the module must _work_. It must enable without errors, have a meaningful title and description, and do what it claims to do. The source code for the module must be published for public review in a software repository at [GitHub.com](https://github.com) and it must have an [open source software license](https://en.wikipedia.org/wiki/Open-source_license). The software must embrace coding styles that will make it reasonably easy to support as REDCap evolves. The software should also embrace REDCap's conventions for data access and data update where practicable. The module should follow EM Framework and software industry conventions for describing its software dependencies. The module should follow REDCap and software industry conventions for securing access to data and software features, sanitizing input, and resisting attack. The full details of the current review guidelines can be found at [External Modules: Module Review Guidelines](https://redcap.vanderbilt.edu/consortium/modules/external_modules_review_guidelines.pdf) The VUMC team's vetting process should never be considered a guarantee of quality, but it definitely _increases_ and _enables_ quality. The guidelines have specific details software developers can follow to improve the quality of their product. The guidelines also protect a module user's ability and right to do their own code review, provide feedback, make improvements, and publish those improvements. + + +## Where to find modules + +The REDCap Repo contains the most REDCap popular. The web interface for the repo is publicly accessible at [https://redcap.vanderbilt.edu/consortium/modules/index.php](https://redcap.vanderbilt.edu/consortium/modules/index.php). The repo's interface allows you to search the database of modules and sort the search results. It provides links to each module's git repo on GitHub.com which can provide details about the state and history of the module. + +The REDCap Repo is also accessible from the REDCap Control Center's _External Module_ page. While all the features of the public page are also accessible from the Control Center link, the REDCap Repo will add links to download modules to the REDCap host when accessed via the Control Center. + +Yet not all modules have been released via the REDCap Repo. Some are not yet ready for publication while others were created to be more site or project specific. A great deal of this development work is happening on Github. Many of those modules can be located by searching Github for specific topics the module development community has been using. Those topics--*redcap-external-module* and _redcap-repo_--can be accessed with these URLs: [https://github.com/topics/redcap-external-module](https://github.com/topics/redcap-external-module), [https://github.com/topics/redcap-repo](https://github.com/topics/redcap-repo). + +If you locate a module of interest to you, you can use the [GitHub.com](https://github.com) web interface to explore the module's state and history. A README.md is the first stop to understand a module's capabilities. A CHANGELOG.md should provide a history of the module's development. The commit history can also provide a development history though it is less curated. Browse through open issues to see outstanding problems. Look at closed issues to see corrected problems. New and completed features are often described through issues as well. + +If you want to install a module that is in Github but not the REDCap Repo, access the repo's _releases_ in Github to download a zipped copy of the module. In many cases, the zip file is 100% of that you need to install the module. You can download it, extract it, rename the unzipped folder with a suffix like "\_v1.0.0" using the version number of the module, then copy that whole folder to the _./modules/_ folder of your REDCap server. At that point it is ready to be enable as if it had been downloaded from the REDCap Repo. + +If you want to follow the development of a module in GitHub, you can create a GitHub account and then _watch_ the module. A GitHub account will also allow you to create and comment on issues for any module. + +One potential point of confusion when you view a module from GitHub is that each module visible in Github is in _git repository_, a term often shortened to _git repo_ or just _repo_. This is not the same kind of repo as the REDCap Repo. They just happen to share the same name. + From e8bb1ab36e0d79288efa55d2525156021d05ee31 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 21 Jan 2020 15:19:54 -0500 Subject: [PATCH 10/77] Update docs/guide_for_admins_and_devs.md Fix typo Co-Authored-By: Kyle Chesney --- docs/guide_for_admins_and_devs.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 6029c8f..f9a7fa2 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -74,5 +74,4 @@ If you want to install a module that is in Github but not the REDCap Repo, acces If you want to follow the development of a module in GitHub, you can create a GitHub account and then _watch_ the module. A GitHub account will also allow you to create and comment on issues for any module. -One potential point of confusion when you view a module from GitHub is that each module visible in Github is in _git repository_, a term often shortened to _git repo_ or just _repo_. This is not the same kind of repo as the REDCap Repo. They just happen to share the same name. - +One potential point of confusion when you view a module from GitHub is that each module visible in Github is in a _git repository_, a term often shortened to _git repo_ or just _repo_. This is not the same kind of repo as the REDCap Repo. They just happen to share the same name. From 54c662eb97d70962c4c6bd4515d87f2fce4144e0 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 21 Jan 2020 15:20:59 -0500 Subject: [PATCH 11/77] Update docs/guide_for_admins_and_devs.md Add link to describe the github watch feature 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 f9a7fa2..4905b91 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -72,6 +72,6 @@ If you locate a module of interest to you, you can use the [GitHub.com](https:// If you want to install a module that is in Github but not the REDCap Repo, access the repo's _releases_ in Github to download a zipped copy of the module. In many cases, the zip file is 100% of that you need to install the module. You can download it, extract it, rename the unzipped folder with a suffix like "\_v1.0.0" using the version number of the module, then copy that whole folder to the _./modules/_ folder of your REDCap server. At that point it is ready to be enable as if it had been downloaded from the REDCap Repo. -If you want to follow the development of a module in GitHub, you can create a GitHub account and then _watch_ the module. A GitHub account will also allow you to create and comment on issues for any module. +If you want to follow the development of a module in GitHub, you can create a GitHub account and then [_watch_](https://help.github.com/en/github/receiving-notifications-about-activity-on-github/watching-and-unwatching-repositories#watching-a-single-repository) the module. A GitHub account will also allow you to create and comment on issues for any module. One potential point of confusion when you view a module from GitHub is that each module visible in Github is in a _git repository_, a term often shortened to _git repo_ or just _repo_. This is not the same kind of repo as the REDCap Repo. They just happen to share the same name. From c777bf2278ee2ac9fc71ddcddff3e741dfe8e446 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 21 Jan 2020 15:23:09 -0500 Subject: [PATCH 12/77] Update docs/guide_for_admins_and_devs.md fix formatting and grammar 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 4905b91..f372071 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -70,7 +70,7 @@ Yet not all modules have been released via the REDCap Repo. Some are not yet rea If you locate a module of interest to you, you can use the [GitHub.com](https://github.com) web interface to explore the module's state and history. A README.md is the first stop to understand a module's capabilities. A CHANGELOG.md should provide a history of the module's development. The commit history can also provide a development history though it is less curated. Browse through open issues to see outstanding problems. Look at closed issues to see corrected problems. New and completed features are often described through issues as well. -If you want to install a module that is in Github but not the REDCap Repo, access the repo's _releases_ in Github to download a zipped copy of the module. In many cases, the zip file is 100% of that you need to install the module. You can download it, extract it, rename the unzipped folder with a suffix like "\_v1.0.0" using the version number of the module, then copy that whole folder to the _./modules/_ folder of your REDCap server. At that point it is ready to be enable as if it had been downloaded from the REDCap Repo. +If you want to install a module that is in Github but not the REDCap Repo, access the repo's _releases_ in Github to download a zipped copy of the module. In many cases, the zip file is 100% of that you need to install the module. You can download it, extract it, rename the unzipped folder with a suffix like "\_v1.0.0" using the version number of the module, then copy that whole folder to the `./modules/` folder of your REDCap server. At that point it is ready to be enabled as if it had been downloaded from the REDCap Repo. If you want to follow the development of a module in GitHub, you can create a GitHub account and then [_watch_](https://help.github.com/en/github/receiving-notifications-about-activity-on-github/watching-and-unwatching-repositories#watching-a-single-repository) the module. A GitHub account will also allow you to create and comment on issues for any module. From 33edfab5848c4ccb8757992c371069327cd6170d Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 21 Jan 2020 15:24:32 -0500 Subject: [PATCH 13/77] Update docs/guide_for_admins_and_devs.md Restructure sentence 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 f372071..acc6b26 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -62,7 +62,7 @@ The VUMC team's vetting process should never be considered a guarantee of qualit ## Where to find modules -The REDCap Repo contains the most REDCap popular. The web interface for the repo is publicly accessible at [https://redcap.vanderbilt.edu/consortium/modules/index.php](https://redcap.vanderbilt.edu/consortium/modules/index.php). The repo's interface allows you to search the database of modules and sort the search results. It provides links to each module's git repo on GitHub.com which can provide details about the state and history of the module. +The REDCap Repo contains most popular REDCap modules. The web interface for the repo is publicly accessible at [https://redcap.vanderbilt.edu/consortium/modules/index.php](https://redcap.vanderbilt.edu/consortium/modules/index.php). The repo's interface allows you to search the database of modules and sort the search results. It provides links to each module's git repo on GitHub.com which can provide details about the state and history of the module. The REDCap Repo is also accessible from the REDCap Control Center's _External Module_ page. While all the features of the public page are also accessible from the Control Center link, the REDCap Repo will add links to download modules to the REDCap host when accessed via the Control Center. From 03e0e90ce5990476561b528e7eeef55e3755ed24 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 21 Jan 2020 15:25:56 -0500 Subject: [PATCH 14/77] 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 acc6b26..4caa352 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -55,7 +55,7 @@ Yet the EM Framework does not stand alone. Many of the features it provides are As of January 2020, the repo contains 133 published modules. This large and growing collection is the database the EM Framework queries for module location and download. It allows the EM Framework to locate module upgrades suitable for a REDCap version and deliver them quickly and easily to the REDCap server. -The vetting process performed by the VUMC REDCap team adds value to the modules in the REDCap Repo. The review process covers the basics but also addresses some esoteric and import details. Most important for the immediate need, the module must _work_. It must enable without errors, have a meaningful title and description, and do what it claims to do. The source code for the module must be published for public review in a software repository at [GitHub.com](https://github.com) and it must have an [open source software license](https://en.wikipedia.org/wiki/Open-source_license). The software must embrace coding styles that will make it reasonably easy to support as REDCap evolves. The software should also embrace REDCap's conventions for data access and data update where practicable. The module should follow EM Framework and software industry conventions for describing its software dependencies. The module should follow REDCap and software industry conventions for securing access to data and software features, sanitizing input, and resisting attack. The full details of the current review guidelines can be found at [External Modules: Module Review Guidelines](https://redcap.vanderbilt.edu/consortium/modules/external_modules_review_guidelines.pdf) +The vetting process performed by the VUMC REDCap team adds value to the modules in the REDCap Repo. The review process covers the basics but also addresses some esoteric and important details. Most importantly for the immediate need, the module must _work_. It must enable without errors, have a meaningful title and description, and do what it claims to do. The source code for the module must be published for public review in a software repository at [GitHub.com](https://github.com) and it must have an [open source software license](https://en.wikipedia.org/wiki/Open-source_license). The software must embrace coding styles that will make it reasonably easy to support as REDCap evolves. The software should also embrace REDCap's conventions for data access and data update where practicable. The module should follow EM Framework and software industry conventions for describing its software dependencies. The module should follow REDCap and software industry conventions for securing access to data and software features, sanitizing input, and resisting attack. The full details of the current review guidelines can be found at [External Modules: Module Review Guidelines](https://redcap.vanderbilt.edu/consortium/modules/external_modules_review_guidelines.pdf) The VUMC team's vetting process should never be considered a guarantee of quality, but it definitely _increases_ and _enables_ quality. The guidelines have specific details software developers can follow to improve the quality of their product. The guidelines also protect a module user's ability and right to do their own code review, provide feedback, make improvements, and publish those improvements. From 42de27447072389d761eaf6200b7bdc8c74895db Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 21 Jan 2020 15:56:06 -0500 Subject: [PATCH 15/77] 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 4caa352..c12fe27 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -30,7 +30,7 @@ Another configuration method was to store the configuration in a record in the r 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 worked right, they work great, but a PHP error in a hook or plugin can be unforgiving. With _PHP errors_ configuration option 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 was as tedious as the deployment. +When hooks worked right, they worked great, but a PHP error in a hook or plugin could be unforgiving. With _PHP errors_ configuration option 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 was as tedious as the 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. From 69de67b03874e797ea1eb00cc20ef0989a3cb1ba Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Wed, 22 Jan 2020 17:12:14 -0500 Subject: [PATCH 16/77] add intro to hooks exercise --- exercises/intro_to_hooks/ExternalModule.php | 27 +++++++++++++++++++++ exercises/intro_to_hooks/README.md | 12 +++++++++ exercises/intro_to_hooks/config.json | 15 ++++++++++++ exercises/intro_to_hooks/js/hello_hook.js | 3 +++ 4 files changed, 57 insertions(+) create mode 100644 exercises/intro_to_hooks/ExternalModule.php create mode 100644 exercises/intro_to_hooks/README.md create mode 100644 exercises/intro_to_hooks/config.json create mode 100644 exercises/intro_to_hooks/js/hello_hook.js diff --git a/exercises/intro_to_hooks/ExternalModule.php b/exercises/intro_to_hooks/ExternalModule.php new file mode 100644 index 0000000..43c2fa7 --- /dev/null +++ b/exercises/intro_to_hooks/ExternalModule.php @@ -0,0 +1,27 @@ +includeJs('js/hello_hook.js'); + $this->setJsSetting('helloHook', 'Hello world!'); + } + + protected function includeJs($file) { + // Use this function to use your JavaScript files in the frontend + echo ''; + } + + protected function setJsSetting($key, $value) { + // Use this function to send variables to the frontend + echo ''; + } +} diff --git a/exercises/intro_to_hooks/README.md b/exercises/intro_to_hooks/README.md new file mode 100644 index 0000000..6a84738 --- /dev/null +++ b/exercises/intro_to_hooks/README.md @@ -0,0 +1,12 @@ +# Hello Hook + +This module provides an alert that notifies users it is active with a friendly "Hello world!" message. + +## Prerequisites +- REDCap >= 8.0.0 (for versions < 8.0.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required). + +## Installation +- Clone this repo into to `/modules/hello_hook_v0.0.0`. +- Go to **Control Center > Manage External Modules** and enable Hello Hook. +- For each project you want to use this module, go to the project home page, click on **Manage External Modules** link, and then enable Auto Populate Fields for that project. + diff --git a/exercises/intro_to_hooks/config.json b/exercises/intro_to_hooks/config.json new file mode 100644 index 0000000..7499c6e --- /dev/null +++ b/exercises/intro_to_hooks/config.json @@ -0,0 +1,15 @@ +{ + "name": "Hello Hook", + "description": "Provide a friendly alert to REDCap users", + "namespace": "HelloHook\\ExternalModule", + "framework-version": 3, + "permissions": [ + ], + "authors": [ + { + "name": "Kyle Chesney", + "email": "kyle.chesney@ufl.edu", + "institution": "University of Florida - CTSI" + } + ] +} diff --git a/exercises/intro_to_hooks/js/hello_hook.js b/exercises/intro_to_hooks/js/hello_hook.js new file mode 100644 index 0000000..655a044 --- /dev/null +++ b/exercises/intro_to_hooks/js/hello_hook.js @@ -0,0 +1,3 @@ +$( document ).ready(function() { + alert(helloHook); +}); From 2f89d111cbd6258441ce3da89e0d9679ec76f6dd Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Wed, 22 Jan 2020 17:12:56 -0500 Subject: [PATCH 17/77] add description of intro to hooks to Jekyll site use Github markdown rendering engine for proper hidden solution --- docs/_config.yml | 2 +- docs/guide_for_devs.md | 24 ++++++++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/_config.yml b/docs/_config.yml index 6a281a4..c03425e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -2,7 +2,7 @@ title: REDCap External Module Development Guide description: REDCap External Module Development Guide repository: ctsit/redcap_external_module_development_guide -markdown: kramdown +markdown: CommonMarkGhPages # ToDo: Review this theme content and remove stuff if it is not needed theme: jekyll-theme-minimal diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index defabfd..535027e 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -47,4 +47,28 @@ Read the section on [module requirements](https://github.com/vanderbilt/redcap-e ### Hello Hook +This module serves as an introduction to hooks. You will learn how to utilise hook functions to run arbitrary code - in this case, a small bit of JavaScript that displays an alert. While you will not be _writing_ any JavaScript for this portion, you will see how to load in JavaScript files, and how to expose backend variables to the frontend. + Read [the official documentation on calling hooks](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#how-to-call-redcap-hooks). + +
+Example Solution + + +`ExternalModule.php` +```php + // FIXME + /* Write your code here */ + function redcap_every_page_top($project_id) { + /* Stop writing code here */ + $this->includeJs('js/hello_hook.js'); +``` + +`config.json` +```json + "permissions": [ + "redcap_every_page_top" + ], +``` + +
From 8769919a856eb37c55dc5555874832aa1b07f89c Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Thu, 23 Jan 2020 10:57:16 -0500 Subject: [PATCH 18/77] scope hello_hook JS variable within an object --- exercises/intro_to_hooks/ExternalModule.php | 11 +++++++---- exercises/intro_to_hooks/js/hello_hook.js | 2 +- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/exercises/intro_to_hooks/ExternalModule.php b/exercises/intro_to_hooks/ExternalModule.php index 43c2fa7..4df5aa7 100644 --- a/exercises/intro_to_hooks/ExternalModule.php +++ b/exercises/intro_to_hooks/ExternalModule.php @@ -11,8 +11,11 @@ class ExternalModule extends AbstractExternalModule { /* Write your code here */ function a_real_redcap_hook() { /* Stop writing code here */ + + // create an empty JS object for the module's variables + echo ''; + $this->setSingleJsSetting('message', 'Hello world!'); $this->includeJs('js/hello_hook.js'); - $this->setJsSetting('helloHook', 'Hello world!'); } protected function includeJs($file) { @@ -20,8 +23,8 @@ protected function includeJs($file) { echo ''; } - protected function setJsSetting($key, $value) { - // Use this function to send variables to the frontend - echo ''; + protected function setSingleJsSetting($key, $value) { + // Use this function to send variables to the frontend scoped within an object + echo ''; } } diff --git a/exercises/intro_to_hooks/js/hello_hook.js b/exercises/intro_to_hooks/js/hello_hook.js index 655a044..b684a5e 100644 --- a/exercises/intro_to_hooks/js/hello_hook.js +++ b/exercises/intro_to_hooks/js/hello_hook.js @@ -1,3 +1,3 @@ $( document ).ready(function() { - alert(helloHook); + alert(helloHook.message); }); From ab73cc7b05f844776f6819ec783dbf96bb4960d7 Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Thu, 23 Jan 2020 11:55:41 -0500 Subject: [PATCH 19/77] add intro to JS exercise, corresponding section on Jekyll site fix typos --- docs/guide_for_devs.md | 75 ++++++++++++++++++++++-- exercises/README.md | 7 ++- exercises/intro_to_js/ExternalModule.php | 30 ++++++++++ exercises/intro_to_js/README.md | 12 ++++ exercises/intro_to_js/config.json | 16 +++++ exercises/intro_to_js/js/intro.js | 6 ++ 6 files changed, 139 insertions(+), 7 deletions(-) create mode 100644 exercises/intro_to_js/ExternalModule.php create mode 100644 exercises/intro_to_js/README.md create mode 100644 exercises/intro_to_js/config.json create mode 100644 exercises/intro_to_js/js/intro.js diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index 535027e..bc2c4cf 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -13,7 +13,7 @@ This guide provides the technical background developers need to write and test m It's essential that you understand how to use REDCap before trying to develop modules for it. Vanderbilt provides a series of videos that provide basic training in how to use REDCap to create and administer instruments and surveys. See [https://projectredcap.org/resources/videos/](https://projectredcap.org/resources/videos/) -The University of Colorado Denver has created a series of videos that address more advanced topics. You can access all of those videos at their [Youtube Playlist](https://www.youtube.com/playlist?list=PLrnf34ZtZ9FpHcZyZuNnNFZ9cEbhijNGf). +The University of Colorado Denver has created a series of videos that address more advanced topics. You can access all of those videos at their [YouTube Playlist](https://www.youtube.com/playlist?list=PLrnf34ZtZ9FpHcZyZuNnNFZ9cEbhijNGf). ### Vanderbilt's External Module Documentation @@ -21,14 +21,14 @@ The University of Colorado Denver has created a series of videos that address mo You will likely find it helpful to keep Vanderbilt's [official External Module documentation](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md) available while completing these exercises; this document will link relevant sections for review. -### REDCap Repo +### REDCap Repo -Vanderbilt publishes modules submitted by the REDCap Community in the [REDCap Repo](https://redcap.vanderbilt.edu/consortium/modules/index.php). The source code for each of these modules is accessible in Github and linked from the entries in the REDCap Repo. These modules provide fully functional code examples. As each module in the REDCap Repo is required to have an open source license, their code can be used in other modules. +Vanderbilt publishes modules submitted by the REDCap Community in the [REDCap Repo](https://redcap.vanderbilt.edu/consortium/modules/index.php). The source code for each of these modules is accessible in GitHub and linked from the entries in the REDCap Repo. These modules provide fully functional code examples. As each module in the REDCap Repo is required to have an open source license, their code can be used in other modules. -### Github +### GitHub -Beyond those in the REDCap Repo, Github.com is commonly used by developers in the REDCap community to host and share modules. Many of these modules are tagged with the topic 'redcap-external-module' and can be located with a [Github topic search](https://github.com/search?q=topic%3Aredcap-external-module&type=Repositories) +Beyond those in the REDCap Repo, [GitHub](https://github.com) is commonly used by developers in the REDCap community to host and share modules. Many of these modules are tagged with the topic 'redcap-external-module' and can be located with a [GitHub topic search](https://github.com/search?q=topic%3Aredcap-external-module&type=Repositories) ## Setting Up Your Environment @@ -40,11 +40,15 @@ Please note that - with the exception of **Hello World** - you will need to mark The External Module Development Guide includes a set of [development exercises](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. +--- + ### Hello World This is a "complete" module intended to be used to make sure your development pipeline is set up properly. Read the section on [module requirements](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#module-requirement) until the section on hooks. +--- + ### Hello Hook This module serves as an introduction to hooks. You will learn how to utilise hook functions to run arbitrary code - in this case, a small bit of JavaScript that displays an alert. While you will not be _writing_ any JavaScript for this portion, you will see how to load in JavaScript files, and how to expose backend variables to the frontend. @@ -72,3 +76,64 @@ Read [the official documentation on calling hooks](https://github.com/vanderbilt ``` +
+ +--- + +### Intro JS + +This module is intended to be used to teach best practices when including JavaScript in your External Modules. It also introduces the use of the REDCap core class, `RCView`; the source for this class is located in the root of your REDCap folder at `Classes/RCView.php` (while clever use of an `onclick` attribute may allow you to complete this module, the purpose is to work with a separate JavaScript file). + +Read [the official documentation on module functions, specifically `getUrl`](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/framework/v3.md). You may also find it helpful to refer to previous exercises where JavaScript was used. + +While this module does not use any variables, note that when working with JavaScript it is [recommended to scope the variables within an object](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#javascript-recommendations). Two sample helper functions to accomplish this goal in PHP are written below. + +```php + protected function setJsSettings($settings) { + echo ''; + } + + // Recall that you must instantiate an empty JS object prior to the first call of this function, i.e. + // echo ''; + protected function setSingleJsSetting($key, $value) { + echo ""; + } +``` + +
+Example Solution + + +`ExternalModule.php` +```php + // FIXME + // include a JavaScript file that increments the contents of incrementValue + // upon clicking the incrementButton + /* write your code below */ + $this->includeJs('js/intro.js'); + } + + protected function includeJs($file) { + // Use this function to use your JavaScript files in the frontend + echo ''; + } +``` + +`js/intro.js` +```javascript +$( document ).ready(function() { + /* Write your code below */ + $('#incrementButton').click(function() { + increase(); + }); +}); + +/* If you wish, make a function */ +function increase() { + let inc = $('#incrementValue').text(); + $('#incrementValue').text(++inc); +} +``` + +
+
diff --git a/exercises/README.md b/exercises/README.md index ff6ed1f..15a94d4 100644 --- a/exercises/README.md +++ b/exercises/README.md @@ -1,12 +1,11 @@ # External Module Development Exercises -The External Module Development Guide includes a set of [development exercises](./) to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. +The External Module Development Guide includes a set of development exercises to use as a guide for module development. Each exercise teaches a different facet of module development. The majority of the exercises are missing essential functionality with comments denoting the regions where the functionality should be added. ## Preface For guidance in developing modules and resources for completing these exercises, see [REDCap External Module Development Guide](https://ctsit.github.io/redcap_external_module_development_guide/). - ## Modules All of module development exercises reside in the Git repo that houses this document at [`https://github.com/ctsit/redcap_external_module_development_guide/exercises/`](https://github.com/ctsit/redcap_external_module_development_guide/exercises/) @@ -19,3 +18,7 @@ Read the section on [module requirements](https://github.com/vanderbilt/redcap-e ### Hello Hook Read [the official documentation on calling hooks](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#how-to-call-redcap-hooks). + +### Intro JS + +Read [the official documentation on module functions, specifically `getUrl`](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/framework/v3.md). You may also find it helpful to refer to previous exercises where JavaScript was used. diff --git a/exercises/intro_to_js/ExternalModule.php b/exercises/intro_to_js/ExternalModule.php new file mode 100644 index 0000000..23e5522 --- /dev/null +++ b/exercises/intro_to_js/ExternalModule.php @@ -0,0 +1,30 @@ + 'btn btn-primary', + 'id' => 'incrementButton' + ]; + $button_text = "Click to increment"; + + // call a prebuilt button maker + echo RCView::button($button_attributes, $button_text); + + echo RCView::p(['id' => 'incrementValue'], '0'); + + // FIXME + // include a JavaScript file that increments the contents of incrementValue + // upon clicking the incrementButton + /* write your code below */ + } + +} diff --git a/exercises/intro_to_js/README.md b/exercises/intro_to_js/README.md new file mode 100644 index 0000000..ea6a637 --- /dev/null +++ b/exercises/intro_to_js/README.md @@ -0,0 +1,12 @@ +# Intro JS + +This module adds a clickable counter to the home page of projects for which it is enabled. + +## Prerequisites +- REDCap >= 8.0.0 (for versions < 8.0.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required). + +## Installation +- Clone this repo into to `/modules/intro_to_js_v0.0.0`. +- Go to **Control Center > Manage External Modules** and enable Intro JS. +- For each project you want to use this module, go to the project home page, click on **Manage External Modules** link, and then enable Intro JS for that project. + diff --git a/exercises/intro_to_js/config.json b/exercises/intro_to_js/config.json new file mode 100644 index 0000000..4438008 --- /dev/null +++ b/exercises/intro_to_js/config.json @@ -0,0 +1,16 @@ +{ + "name": "Intro JS", + "description": "Adds a counter to the home page", + "namespace": "IntroJS\\ExternalModule", + "framework-version": 3, + "permissions": [ + "redcap_project_home_page" + ], + "authors": [ + { + "name": "Kyle Chesney", + "email": "kyle.chesney@ufl.edu", + "institution": "University of Florida - CTSI" + } + ] +} diff --git a/exercises/intro_to_js/js/intro.js b/exercises/intro_to_js/js/intro.js new file mode 100644 index 0000000..8da8a5e --- /dev/null +++ b/exercises/intro_to_js/js/intro.js @@ -0,0 +1,6 @@ +$( document ).ready(function() { + /* Write your code below */ + +}); + +/* If you wish, make a function */ From 0a2089624211e1c05fc924455712a384e304dc09 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Thu, 23 Jan 2020 15:34:02 -0500 Subject: [PATCH 20/77] Add abstracted links to our repo in GitHub Add abstracted links in guide_for_devs.md. Set repo_root variable in _config.yml. Add script with instructions to override repo_root locally. --- .gitignore | 3 ++- docs/_config.yml | 2 ++ docs/guide_for_devs.md | 6 +++--- docs/script/serve.sh | 15 +++++++++++++++ 4 files changed, 22 insertions(+), 4 deletions(-) create mode 100755 docs/script/serve.sh diff --git a/.gitignore b/.gitignore index 30c9bf8..44898cd 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,5 @@ _site/ .jekyll-cache/ .jekyll-metadata Gemfile.lock -*.gem \ No newline at end of file +*.gem +_config_local.yaml diff --git a/docs/_config.yml b/docs/_config.yml index c03425e..008d331 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -2,6 +2,8 @@ title: REDCap External Module Development Guide description: REDCap External Module Development Guide repository: ctsit/redcap_external_module_development_guide +repo_root: https://github.com/ctsit/redcap_external_module_development_guide/ + markdown: CommonMarkGhPages # ToDo: Review this theme content and remove stuff if it is not needed diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index bc2c4cf..4431d5e 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -42,14 +42,14 @@ The External Module Development Guide includes a set of [development exercises]( --- -### Hello World +### [Hello World]({{ site.repo_root }}/exercises/hello_world_v0.0.0/) This is a "complete" module intended to be used to make sure your development pipeline is set up properly. Read the section on [module requirements](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#module-requirement) until the section on hooks. --- -### Hello Hook +### [Hello Hook]({{ site.repo_root }}/exercises/intro_to_hooks/) This module serves as an introduction to hooks. You will learn how to utilise hook functions to run arbitrary code - in this case, a small bit of JavaScript that displays an alert. While you will not be _writing_ any JavaScript for this portion, you will see how to load in JavaScript files, and how to expose backend variables to the frontend. @@ -80,7 +80,7 @@ Read [the official documentation on calling hooks](https://github.com/vanderbilt --- -### Intro JS +### [Intro JS]({{ site.repo_root }}/exercises/intro_to_js/) This module is intended to be used to teach best practices when including JavaScript in your External Modules. It also introduces the use of the REDCap core class, `RCView`; the source for this class is located in the root of your REDCap folder at `Classes/RCView.php` (while clever use of an `onclick` attribute may allow you to complete this module, the purpose is to work with a separate JavaScript file). diff --git a/docs/script/serve.sh b/docs/script/serve.sh new file mode 100755 index 0000000..83d632f --- /dev/null +++ b/docs/script/serve.sh @@ -0,0 +1,15 @@ +# To override variables in _config.yml for use in your local environment, +# set those variables in _config_local.yaml. E.g. add a line like this to +# link to the root of the develop branch of the CTSIT fork: +# +# repo_root: https://github.com/ctsit/redcap_external_module_development_guide/tree/develop +# +# This script will load the contents of _config_local.yaml last if it exists. +# Github will only reference _config.yaml when building the site. + +# Note: You might need to tell rvm which ruby to use before running this script. e.g. +# +# rvm use 2.6.3 +# + +bundle exec jekyll serve --config _config.yml,_config_local.yaml From 7db32ea8e65f1174f1b76a92eb4cf65df7a633e4 Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Thu, 23 Jan 2020 16:00:34 -0500 Subject: [PATCH 21/77] adjust slashes in directories to mirror config.yml --- docs/guide_for_devs.md | 6 +++--- docs/script/serve.sh | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index 4431d5e..0a49528 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -42,14 +42,14 @@ The External Module Development Guide includes a set of [development exercises]( --- -### [Hello World]({{ site.repo_root }}/exercises/hello_world_v0.0.0/) +### [Hello World]({{ site.repo_root }}exercises/hello_world_v0.0.0/) This is a "complete" module intended to be used to make sure your development pipeline is set up properly. Read the section on [module requirements](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#module-requirement) until the section on hooks. --- -### [Hello Hook]({{ site.repo_root }}/exercises/intro_to_hooks/) +### [Hello Hook]({{ site.repo_root }}exercises/intro_to_hooks/) This module serves as an introduction to hooks. You will learn how to utilise hook functions to run arbitrary code - in this case, a small bit of JavaScript that displays an alert. While you will not be _writing_ any JavaScript for this portion, you will see how to load in JavaScript files, and how to expose backend variables to the frontend. @@ -80,7 +80,7 @@ Read [the official documentation on calling hooks](https://github.com/vanderbilt --- -### [Intro JS]({{ site.repo_root }}/exercises/intro_to_js/) +### [Intro JS]({{ site.repo_root }}exercises/intro_to_js/) This module is intended to be used to teach best practices when including JavaScript in your External Modules. It also introduces the use of the REDCap core class, `RCView`; the source for this class is located in the root of your REDCap folder at `Classes/RCView.php` (while clever use of an `onclick` attribute may allow you to complete this module, the purpose is to work with a separate JavaScript file). diff --git a/docs/script/serve.sh b/docs/script/serve.sh index 83d632f..9d0c902 100755 --- a/docs/script/serve.sh +++ b/docs/script/serve.sh @@ -2,7 +2,7 @@ # set those variables in _config_local.yaml. E.g. add a line like this to # link to the root of the develop branch of the CTSIT fork: # -# repo_root: https://github.com/ctsit/redcap_external_module_development_guide/tree/develop +# repo_root: https://github.com/ctsit/redcap_external_module_development_guide/tree/develop/ # # This script will load the contents of _config_local.yaml last if it exists. # Github will only reference _config.yaml when building the site. From efedad493e3cf83372cd1ae4678cc3ff77da87c6 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Thu, 23 Jan 2020 16:32:35 -0500 Subject: [PATCH 22/77] Test for _config_local.yaml before trying to use it --- docs/script/serve.sh | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/script/serve.sh b/docs/script/serve.sh index 9d0c902..ae2615c 100755 --- a/docs/script/serve.sh +++ b/docs/script/serve.sh @@ -12,4 +12,10 @@ # rvm use 2.6.3 # -bundle exec jekyll serve --config _config.yml,_config_local.yaml +LOCAL_CONFIG_YAML=_config_local.yaml + +if [ -e ${LOCAL_CONFIG_YAML} ]; then + bundle exec jekyll serve --config _config.yml,${LOCAL_CONFIG_YAML} +else + bundle exec jekyll serve +fi From 437361d163195ddcfe69c76176cf1f630bd076f8 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 27 Jan 2020 06:34:54 -0500 Subject: [PATCH 23/77] Add 'Contributing to modules' to guide_for_admins_and_devs.md --- docs/guide_for_admins_and_devs.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index c12fe27..4cd4313 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -75,3 +75,12 @@ If you want to install a module that is in Github but not the REDCap Repo, acces If you want to follow the development of a module in GitHub, you can create a GitHub account and then [_watch_](https://help.github.com/en/github/receiving-notifications-about-activity-on-github/watching-and-unwatching-repositories#watching-a-single-repository) the module. A GitHub account will also allow you to create and comment on issues for any module. One potential point of confusion when you view a module from GitHub is that each module visible in Github is in a _git repository_, a term often shortened to _git repo_ or just _repo_. This is not the same kind of repo as the REDCap Repo. They just happen to share the same name. + + +## Contributing to modules + +While this guide is ostensibly about developing modules, writing code is hardly the only way to contribute to the creation, maintenance and quality of modules or any other software. Even a small program can generate plenty of work that is not writing code. Every program needs documentation that describes how to install, configure and use it. Contributors should be acknowledged in the documentation. Questions about the software need to be answered. Bugs need to be written up. Feature requests need to be reviewed and improved until they make sense to everyone. Software changes need to be tested. + +While you can give all of these tasks to software developers, most developers appreciate not having to do _everything_. At the same time, adding the perspective of another person to a project can greatly improve the quality. + +Such contributions need not even be to your own team's project. It is easy to contribute to any project being developed publicly in GitHub. One need only create a GitHub account and start contributing through the GitHub issues list on the project. Issues are the first place to pose questions, offer assistance, contribute to a discussion, or find tasks to work on. Everything else can flow from there. From 6c52e1858964b69ed1765b95c252d04b87072afa Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 27 Jan 2020 08:01:06 -0500 Subject: [PATCH 24/77] Add sections to guide_for_admins_and_devs.md Add 'Developing your own modules'. Add 'Finding and training a developer'. --- docs/guide_for_admins_and_devs.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 4cd4313..27fce73 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -84,3 +84,27 @@ While this guide is ostensibly about developing modules, writing code is hardly While you can give all of these tasks to software developers, most developers appreciate not having to do _everything_. At the same time, adding the perspective of another person to a project can greatly improve the quality. Such contributions need not even be to your own team's project. It is easy to contribute to any project being developed publicly in GitHub. One need only create a GitHub account and start contributing through the GitHub issues list on the project. Issues are the first place to pose questions, offer assistance, contribute to a discussion, or find tasks to work on. Everything else can flow from there. + + +## Developing your own modules + +If you are going to develop your own modules, there are several issues to address to increase your odds of success. Someone needs to design and write the code. Those skills have be sourced and the person doing the work will need some REDCap training. The development work that person does needs to be reviewed by someone else. The reviewer needs the technical means to test the software and a good workflow for providing feedback. The software needs a good home that lends itself to software development workflows. The choice of homes for the software could be influenced by a need to share the software. Sharing software means a good license agreement will be important. + +Ignore these details at your own peril. + + +## Finding and training a developer + +While there are a great many contributions a non-developer can make to a module, if you are going to develop your own modules, you will need the skills of a software developer. This raises the issues of sourcing and training that talent. + +At an educational institution, students in computer science, data science or informatics programs often make good hires. While their specific skills might be in the wrong languages for REDCap development, they can often learn the languages needed. If you have the means to hire a professional developer, do it. Professional experience will generally allow your new hire to be productive sooner than someone who has not worked with as many of the tools involved. + +The right candidate for the job will be someone who can demonstrate curiosity and initiative. No one--not even the professional developer--will know everything they need to develop a REDCap module. They will need a willingness to learn REDCap both as a user and an admin while also learning enough of the REDCap code to extend it. + +The technical skills needed are in JavaScript and PHP. JavaScript skills are found in anyone that calls themselves a _front end web developer_. Look for someone who has demonstrated their skills in JavaScript on the job, in an open source project or in work of their own. PHP skills are harder to find than Javascript skills, but they will also be needed for the job. You might have to accept a candidate who has not coded in PHP but seems able to learn. + +Ask candidates if they have a public GitHub repository. Not everyone has this, but, where they exist, they provide an opportunity to see the candidate's code first-hand. These repos also demonstrate some experience with GitHub, git, and open source software development. All of these are important for module development. + +Once you have hired a developer, they will need to be trained. Even the best candidates are not likely to know anything about REDCap. Train every developer as if they are to become a REDCap Admin. Have them watch all of VUMC's [REDCap training videos](https://projectredcap.org/resources/videos/). Assign them a complicated project building task or a series of tasks that will require they use all the common features of REDCap. Have your new hire read this document at [https://ctsit.github.io/redcap_external_module_development_guide/](https://ctsit.github.io/redcap_external_module_development_guide/) Have them build all of the exercise modules at [https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs](https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs) + +Your new hire should not work alone. Connect them to the REDCap community. Sign them up for the REDCap Community website. Introduce them to developers you know so they can feel a part of that sub-community as well. Invite them to REDCapCon. From 4280bfd77e9ede0e4a40f0cb9b39fe2f60ecbe27 Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Mon, 27 Jan 2020 08:52:44 -0500 Subject: [PATCH 25/77] improve descriptions, correct versions, slim down Hello World --- exercises/hello_world_v0.0.0/config.json | 67 +------------------ .../pages/control_center_custom_page.php | 11 --- .../pages/project_custom_page.php | 11 --- exercises/intro_to_hooks/README.md | 6 +- exercises/intro_to_js/README.md | 6 +- exercises/intro_to_js/config.json | 2 +- 6 files changed, 8 insertions(+), 95 deletions(-) delete mode 100644 exercises/hello_world_v0.0.0/pages/control_center_custom_page.php delete mode 100644 exercises/hello_world_v0.0.0/pages/project_custom_page.php diff --git a/exercises/hello_world_v0.0.0/config.json b/exercises/hello_world_v0.0.0/config.json index 3e7effc..b841753 100644 --- a/exercises/hello_world_v0.0.0/config.json +++ b/exercises/hello_world_v0.0.0/config.json @@ -11,71 +11,6 @@ "name": "Kyle Chesney", "email": "kyle.chesney@ufl.edu", "institution": "University of Florida - CTSI" - }, - { - "name": "Tiago Bember", - "email": "tbembersimeao@ufl.edu", - "institution": "University of Florida - CTSI" - } - ], - "project-settings": [ - { - "name": "Text entry", - "key": "text_entry", - "type": "text" - }, - { - "name": "Select", - "key": "dummy_select", - "type": "dropdown", - "choices": [ - { - "value": "a", - "name": "A" - }, - { - "value": "b", - "name": "B" - } - ] } - ], - "system-settings": [ - { - "name": "Dummy config system", - "key": "dummy_cfg_system", - "type": "text" - }, - { - "name": "Select system", - "key": "dummy_select_system", - "type": "radio", - "choices": [ - { - "value": "c", - "name": "C" - }, - { - "value": "d", - "name": "D" - } - ] - } - ], - "links": { - "project": [ - { - "name": "Hello Project", - "icon": "fas globe", - "url": "pages/project_custom_page.php" - } - ], - "control-center": [ - { - "name": "Hello Admin", - "icon": "fas fa-globe", - "url": "pages/control_center_custom_page.php" - } - ] - } + ] } diff --git a/exercises/hello_world_v0.0.0/pages/control_center_custom_page.php b/exercises/hello_world_v0.0.0/pages/control_center_custom_page.php deleted file mode 100644 index a45564f..0000000 --- a/exercises/hello_world_v0.0.0/pages/control_center_custom_page.php +++ /dev/null @@ -1,11 +0,0 @@ - APP_PATH_IMAGES . 'bell.png']) . ' ' . REDCap::escapeHtml('Control Center Page'); -echo RCView::h4([], $title); -echo 'Hello World!!'; - -require_once APP_PATH_DOCROOT . 'ControlCenter/footer.php'; diff --git a/exercises/hello_world_v0.0.0/pages/project_custom_page.php b/exercises/hello_world_v0.0.0/pages/project_custom_page.php deleted file mode 100644 index fadf247..0000000 --- a/exercises/hello_world_v0.0.0/pages/project_custom_page.php +++ /dev/null @@ -1,11 +0,0 @@ - APP_PATH_IMAGES . 'bell.png']) . ' ' . REDCap::escapeHtml('Control Center Page'); -echo RCView::h4([], $title); -echo 'Hello World!!'; - -require_once APP_PATH_DOCROOT . 'ProjectGeneral/footer.php'; diff --git a/exercises/intro_to_hooks/README.md b/exercises/intro_to_hooks/README.md index 6a84738..c0c07eb 100644 --- a/exercises/intro_to_hooks/README.md +++ b/exercises/intro_to_hooks/README.md @@ -3,10 +3,10 @@ This module provides an alert that notifies users it is active with a friendly "Hello world!" message. ## Prerequisites -- REDCap >= 8.0.0 (for versions < 8.0.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required). +- REDCap >= 8.0.3 (for versions < 8.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required). ## Installation - Clone this repo into to `/modules/hello_hook_v0.0.0`. -- Go to **Control Center > Manage External Modules** and enable Hello Hook. -- For each project you want to use this module, go to the project home page, click on **Manage External Modules** link, and then enable Auto Populate Fields for that project. +- Go to **Control Center > Manage External Modules** and enable **Hello Hook**. +- For each project you want to use this module, go to the project home page, click on **Manage External Modules** link, and then enable **Hello Hook** for that project. diff --git a/exercises/intro_to_js/README.md b/exercises/intro_to_js/README.md index ea6a637..1a6253e 100644 --- a/exercises/intro_to_js/README.md +++ b/exercises/intro_to_js/README.md @@ -3,10 +3,10 @@ This module adds a clickable counter to the home page of projects for which it is enabled. ## Prerequisites -- REDCap >= 8.0.0 (for versions < 8.0.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required). +- REDCap >= 8.0.3 (for versions < 8.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required). ## Installation - Clone this repo into to `/modules/intro_to_js_v0.0.0`. -- Go to **Control Center > Manage External Modules** and enable Intro JS. -- For each project you want to use this module, go to the project home page, click on **Manage External Modules** link, and then enable Intro JS for that project. +- Go to **Control Center > Manage External Modules** and enable **Intro JS**. +- For each project you want to use this module, go to the project home page, click on **Manage External Modules** link, and then enable **Intro JS** for that project. diff --git a/exercises/intro_to_js/config.json b/exercises/intro_to_js/config.json index 4438008..eb8af45 100644 --- a/exercises/intro_to_js/config.json +++ b/exercises/intro_to_js/config.json @@ -1,6 +1,6 @@ { "name": "Intro JS", - "description": "Adds a counter to the home page", + "description": "Adds a counter to the project home page", "namespace": "IntroJS\\ExternalModule", "framework-version": 3, "permissions": [ From 805dd4878e6a0c4eb1a1894bd60af8b40e10b5a4 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 27 Jan 2020 09:33:42 -0500 Subject: [PATCH 26/77] Update docs/guide_for_admins_and_devs.md Acknowledge the programming experience in other fields 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 27fce73..ea12a03 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -97,7 +97,7 @@ Ignore these details at your own peril. While there are a great many contributions a non-developer can make to a module, if you are going to develop your own modules, you will need the skills of a software developer. This raises the issues of sourcing and training that talent. -At an educational institution, students in computer science, data science or informatics programs often make good hires. While their specific skills might be in the wrong languages for REDCap development, they can often learn the languages needed. If you have the means to hire a professional developer, do it. Professional experience will generally allow your new hire to be productive sooner than someone who has not worked with as many of the tools involved. +At an educational institution, students in computer science, data science or informatics programs often make good hires; students in other technical programs are increasingly exposed to programming languages during data analysis. While their specific skills might be in the wrong languages for REDCap development, they can often learn the languages needed. If you have the means to hire a professional developer, do it. Professional experience will generally allow your new hire to be productive sooner than someone who has not worked with as many of the tools involved. The right candidate for the job will be someone who can demonstrate curiosity and initiative. No one--not even the professional developer--will know everything they need to develop a REDCap module. They will need a willingness to learn REDCap both as a user and an admin while also learning enough of the REDCap code to extend it. From 21df0fd0cd5bc4429f2ffa8f78fc8a3da7b029b0 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Mon, 27 Jan 2020 09:36:20 -0500 Subject: [PATCH 27/77] Update docs/guide_for_admins_and_devs.md Add links to Project REDCap resources 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 ea12a03..cc45a18 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -107,4 +107,4 @@ Ask candidates if they have a public GitHub repository. Not everyone has this, b Once you have hired a developer, they will need to be trained. Even the best candidates are not likely to know anything about REDCap. Train every developer as if they are to become a REDCap Admin. Have them watch all of VUMC's [REDCap training videos](https://projectredcap.org/resources/videos/). Assign them a complicated project building task or a series of tasks that will require they use all the common features of REDCap. Have your new hire read this document at [https://ctsit.github.io/redcap_external_module_development_guide/](https://ctsit.github.io/redcap_external_module_development_guide/) Have them build all of the exercise modules at [https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs](https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs) -Your new hire should not work alone. Connect them to the REDCap community. Sign them up for the REDCap Community website. Introduce them to developers you know so they can feel a part of that sub-community as well. Invite them to REDCapCon. +Your new hire should not work alone. Connect them to the REDCap community. Sign them up for the [REDCap Community website](https://projectredcap.org/resources/community/). Introduce them to developers you know so they can feel a part of that sub-community as well. Invite them to [REDCapCon](https://projectredcap.org/about/redcapcon/). From 623ccb9d94d2fc8e81d6e90273924ad452193cae Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 28 Jan 2020 07:57:35 -0500 Subject: [PATCH 28/77] Add 'Finding a home for your software' --- docs/guide_for_admins_and_devs.md | 22 ++++++++++++++++++++++ docs/script/serve.sh | 21 +++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100755 docs/script/serve.sh diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index cc45a18..1b841c5 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -108,3 +108,25 @@ Ask candidates if they have a public GitHub repository. Not everyone has this, b Once you have hired a developer, they will need to be trained. Even the best candidates are not likely to know anything about REDCap. Train every developer as if they are to become a REDCap Admin. Have them watch all of VUMC's [REDCap training videos](https://projectredcap.org/resources/videos/). Assign them a complicated project building task or a series of tasks that will require they use all the common features of REDCap. Have your new hire read this document at [https://ctsit.github.io/redcap_external_module_development_guide/](https://ctsit.github.io/redcap_external_module_development_guide/) Have them build all of the exercise modules at [https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs](https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs) Your new hire should not work alone. Connect them to the REDCap community. Sign them up for the [REDCap Community website](https://projectredcap.org/resources/community/). Introduce them to developers you know so they can feel a part of that sub-community as well. Invite them to [REDCapCon](https://projectredcap.org/about/redcapcon/). + + +## Finding a home for your software + +Every software project needs a good home to help it be successful. The software engineers have created tools to help them do their jobs. One of those foundational tools is _version control_. Version control software tracks the changes to files that make up a computer program, web site, documentation suite or _anything_. It documents the history of who did what when to which files. It documents the branching and rejoining any project experiences when there are multiple authors involved. + +There are multiple version control packages to choose from, but the dominate player is _git_. It's high function, free, well-documented, works on the command line, and has multiple GUI interfaces. git houses the software that runs the Internet. VUMC moved the REDCap code into git a few years back. They also require git for all modules submitted to the REDCap Repo. + +Git stores the documents of a project in a repository or _repo_. Outwardly it looks like a folder full of files, but it contains a hidden folder that holds the entire history of the repository from creation to its current state. Every version of every file ever added to repository is in the hidden folder. Even deleted files are preserved there. This history records who made each revision, when they made the change and what other files changed at the same time. There's a description for each change as well. The history is immutable. You can't go back and pretend a change made 2 years ago didn't happen without rewriting all the history since then. + +Yet git is only one dimension of finding a home for your project. While the software lives in a git repo, the repo must live somewhere as well. Such a service is called _source code hosting_. A good host for your project's repo will make it accessible to everyone who needs to get to it. The host will provide access controls to make sure the right people can read and write to the repo. The source code host provides a place to talk about the evolution of the software, see proposed changes, review them and merge them into the master branch of the project. + +One of the big players in source code hosting is [GitHub.com](https://github.com). They provide all of the above services and more on their platform--a web-based service that specializes in hosting git repositories. They provide both free and paid levels of service. The free service is well-suited to hosting open-source software projects and has captured a lot of that market. + +VUMC requires REDCap modules that want to be included in the REDCap Repo to be hosted in publicly-accessible software repositories on GitHub. This makes it simple for REDCap community members to share their work with both the VUMC REDCap team and the entire REDCap community. + +Even without VUMC's requirement to use it, GitHub is still an excellent choice for hosting the development of a REDCap module or any software development project. GitHub's software enables a collaborative process of development for the software and its documentation. It allows anyone to participate as a peer in the process of creating, enhancing and maintaining a project. The service is free for public repos and it is centered around free tools. This lowers potential barriers to entry for collaborators. + +Easy paths to sharing the tools of clinical and translation research are important. In some cases, the funding sources for REDCap teams at academic health centers in the USA require sharing the works created with that funding. This is true of many NIH-funded projects and specifically the Clinical and Translational Science Awards (CTSAs) that fund many of the largest clinical research universities in the US. REDCap modules created at those institutions are one of those products that should be shared because of the funding sources. + +Yet sharing a continually evolving product can be challenging. Using platform like GitHub that is designed to for sharing and collaboration makes it much simpler. It provides tools and workflows to reduce the labor of sharing and more quickly and reliably deliver the latest iteration of a software package to those who need it. + diff --git a/docs/script/serve.sh b/docs/script/serve.sh new file mode 100755 index 0000000..ae2615c --- /dev/null +++ b/docs/script/serve.sh @@ -0,0 +1,21 @@ +# To override variables in _config.yml for use in your local environment, +# set those variables in _config_local.yaml. E.g. add a line like this to +# link to the root of the develop branch of the CTSIT fork: +# +# repo_root: https://github.com/ctsit/redcap_external_module_development_guide/tree/develop/ +# +# This script will load the contents of _config_local.yaml last if it exists. +# Github will only reference _config.yaml when building the site. + +# Note: You might need to tell rvm which ruby to use before running this script. e.g. +# +# rvm use 2.6.3 +# + +LOCAL_CONFIG_YAML=_config_local.yaml + +if [ -e ${LOCAL_CONFIG_YAML} ]; then + bundle exec jekyll serve --config _config.yml,${LOCAL_CONFIG_YAML} +else + bundle exec jekyll serve +fi From 9ff99ca1a950d0e66e286bbeafdbcd184ebc299a Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Tue, 28 Jan 2020 23:01:51 -0500 Subject: [PATCH 29/77] Add 'Eat your own dog food' to guide_for_admins_and_devs.md --- docs/guide_for_admins_and_devs.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 1b841c5..587010a 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -112,9 +112,9 @@ Your new hire should not work alone. Connect them to the REDCap community. Sign ## Finding a home for your software -Every software project needs a good home to help it be successful. The software engineers have created tools to help them do their jobs. One of those foundational tools is _version control_. Version control software tracks the changes to files that make up a computer program, web site, documentation suite or _anything_. It documents the history of who did what when to which files. It documents the branching and rejoining any project experiences when there are multiple authors involved. +Every software project needs a good home to be successful. The most foundational part of that home is _version control_. Version control software tracks the changes to files that make up a computer program, web site, documentation suite or _anything_. It documents the history of who did what when to which files. It documents the branching and rejoining any project experiences when there are multiple authors involved. -There are multiple version control packages to choose from, but the dominate player is _git_. It's high function, free, well-documented, works on the command line, and has multiple GUI interfaces. git houses the software that runs the Internet. VUMC moved the REDCap code into git a few years back. They also require git for all modules submitted to the REDCap Repo. +There are multiple version control packages to choose from, but the dominate player is _git_. It's high function, free, well-documented, works on the command line, and has multiple GUI interfaces. Git houses the software that runs the Internet. VUMC moved the REDCap code into git a few years back. They also require git for all modules submitted to the REDCap Repo. Git stores the documents of a project in a repository or _repo_. Outwardly it looks like a folder full of files, but it contains a hidden folder that holds the entire history of the repository from creation to its current state. Every version of every file ever added to repository is in the hidden folder. Even deleted files are preserved there. This history records who made each revision, when they made the change and what other files changed at the same time. There's a description for each change as well. The history is immutable. You can't go back and pretend a change made 2 years ago didn't happen without rewriting all the history since then. @@ -124,9 +124,24 @@ One of the big players in source code hosting is [GitHub.com](https://github.com VUMC requires REDCap modules that want to be included in the REDCap Repo to be hosted in publicly-accessible software repositories on GitHub. This makes it simple for REDCap community members to share their work with both the VUMC REDCap team and the entire REDCap community. -Even without VUMC's requirement to use it, GitHub is still an excellent choice for hosting the development of a REDCap module or any software development project. GitHub's software enables a collaborative process of development for the software and its documentation. It allows anyone to participate as a peer in the process of creating, enhancing and maintaining a project. The service is free for public repos and it is centered around free tools. This lowers potential barriers to entry for collaborators. +Even without VUMC's requirement to use it, GitHub is still an excellent choice for hosting the development of a REDCap module or any software development project. GitHub's software enables a collaborative process of development for the software and its documentation. It allows anyone to participate as a peer in the process of creating, enhancing and maintaining a project. The service is free for public repos and it is centered around free tools. This zero cost for the tools of software development lowers potential barriers to entry for collaborators. Easy paths to sharing the tools of clinical and translation research are important. In some cases, the funding sources for REDCap teams at academic health centers in the USA require sharing the works created with that funding. This is true of many NIH-funded projects and specifically the Clinical and Translational Science Awards (CTSAs) that fund many of the largest clinical research universities in the US. REDCap modules created at those institutions are one of those products that should be shared because of the funding sources. -Yet sharing a continually evolving product can be challenging. Using platform like GitHub that is designed to for sharing and collaboration makes it much simpler. It provides tools and workflows to reduce the labor of sharing and more quickly and reliably deliver the latest iteration of a software package to those who need it. +Yet sharing a continually evolving product can be challenging. The pace of change in software development can leave fixes untested or not shared. Using a good hosting platform makes sharing and collaboration much simpler. GitHub provides tools and workflows to reduce the labor of sharing and more quickly and reliably deliver the latest iteration of a software package to those who need it. +## Eat your own dog food + +One impediment to reliable and quick delivery of software changes is a reluctance to embrace the product we deliver. Some teams like to use two software repositories for the same project. There is a public-facing repository that has code judged to be safe, clean, good, and suitable for public consumption. Then there is a private repository that has the real code that gets work done for the team. This is a Bad Idea. + +In this all-too-common development workflow, ideas are implemented in the private repo first. They are tested and refined until they work. The code might be ugly; it might have local details; it might have passwords and other secrets embedded in it. Yet all of that is OK because the code works. + +In the next step of the development workflow, the developer makes the code pretty; they make it configurable; they take the passwords out; they take out the secrets; they remove everything embarassing and unshareable. Yet all of this takes time because it's hard to make non-portable software portable. Then someone realizes there's no documentation for the software so the project takes even more time to make it suitable for a public audience. + +Meanwhile, internal priorities have forced the private repo to evolve to meet local needs. The public repo has fallen behind and it's only just been released. Changing the local deployment workflows to use the public repo would cost even more time so it doesn't ever happen. The public repo is always a second class citizen. + +The problem in this scenario is the authors of the software are not willing to use their own product. In the parlance of the software industry, they are unwilling to "Eat their own dog food". The author who won't use their own product, will never understand what is wrong with it and will never make it better. + +To drive quality, the team should use its own product. To make the software portable, configurability should be baked in from the start. If the software is configurable from the beginning, there is no motivation to commit local configuration and secrets into the software. The test datasets the developers create to test their work should become part of the repo so other people can more rapidly test and demonstrate the software. To keep identifiable data out of the test data, developers should not be exposed to PHI or PII until they have demonstrated a respect for the risks it creates. If each of these rules is followed in writing the software, it will be ready for a public-facing repo on the day the project starts. + +Yet there remains a tendency for people to think their code is not good enough to share. Nothing could be further from the truth. If the code works for the author, it is good enough to share. It might not work for the next person, but if they give feedback, their failure can help make the code better. Sharing early is always better. From 0d08e2c9796eb53d3ed616bb32326482a1850d81 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Wed, 29 Jan 2020 07:27:29 -0500 Subject: [PATCH 30/77] Add rant to 'Eat your own dog food' --- docs/guide_for_admins_and_devs.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index 587010a..68973e2 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -132,16 +132,18 @@ Yet sharing a continually evolving product can be challenging. The pace of chang ## Eat your own dog food -One impediment to reliable and quick delivery of software changes is a reluctance to embrace the product we deliver. Some teams like to use two software repositories for the same project. There is a public-facing repository that has code judged to be safe, clean, good, and suitable for public consumption. Then there is a private repository that has the real code that gets work done for the team. This is a Bad Idea. +One impediment to reliable and quick delivery of software changes is a reluctance to embrace the product we deliver. Some teams like to use two software repositories for the same project. There is a public-facing repository that has code judged to be safe, clean, good, and suitable for public consumption. Then there is a private repository that has the real code that gets work done for the team. This might seem like a good way to share one's product, but it is the very opposite. It allows the authors to claim to share the product of their labors while doing a crummy job of it. In this all-too-common development workflow, ideas are implemented in the private repo first. They are tested and refined until they work. The code might be ugly; it might have local details; it might have passwords and other secrets embedded in it. Yet all of that is OK because the code works. In the next step of the development workflow, the developer makes the code pretty; they make it configurable; they take the passwords out; they take out the secrets; they remove everything embarassing and unshareable. Yet all of this takes time because it's hard to make non-portable software portable. Then someone realizes there's no documentation for the software so the project takes even more time to make it suitable for a public audience. -Meanwhile, internal priorities have forced the private repo to evolve to meet local needs. The public repo has fallen behind and it's only just been released. Changing the local deployment workflows to use the public repo would cost even more time so it doesn't ever happen. The public repo is always a second class citizen. +Meanwhile, internal priorities have forced the private repo to evolve to meet local needs. The public repo has fallen behind and it's only just been released. Changing the local deployment workflow to use the public repo would cost even more time so it doesn't happen. The cycle repeats with minor variants with every improvement to the software. + +The public repo remains a second class citizen forever. The consumers' questions annoy the developers because they already encountered those bugs and fixed them, but only in the local version. Porting those fixes into the public repo is always extra work. It grates on the developers' nerves. They grow to hate the public code and its consumers, but they never realize they are part of the problem. The developers' masters enjoy taking credit for sharing, but, with the developers talking about the additional labor of porting the local code to the public repo, they get the impression that sharing is expensive. They question the value of sharing without ever realizing they are part of the problem as well lowering the quality of what they share while increasing its cost. The problem in this scenario is the authors of the software are not willing to use their own product. In the parlance of the software industry, they are unwilling to "Eat their own dog food". The author who won't use their own product, will never understand what is wrong with it and will never make it better. To drive quality, the team should use its own product. To make the software portable, configurability should be baked in from the start. If the software is configurable from the beginning, there is no motivation to commit local configuration and secrets into the software. The test datasets the developers create to test their work should become part of the repo so other people can more rapidly test and demonstrate the software. To keep identifiable data out of the test data, developers should not be exposed to PHI or PII until they have demonstrated a respect for the risks it creates. If each of these rules is followed in writing the software, it will be ready for a public-facing repo on the day the project starts. -Yet there remains a tendency for people to think their code is not good enough to share. Nothing could be further from the truth. If the code works for the author, it is good enough to share. It might not work for the next person, but if they give feedback, their failure can help make the code better. Sharing early is always better. +Yet there remains a tendency for people to think their code is not good enough to share. Nothing could be further from the truth. If the code works for the author, it is good enough to share. It might not work for the next person, but if they give feedback, their failure can help make the code better. Sharing early is always better. It makes better products. It lowers the cost of sharing. From 7ee0cddbf42942028bff64892c941af4770f4abe Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Wed, 29 Jan 2020 07:31:42 -0500 Subject: [PATCH 31/77] Remove docs/script/serve.sh This was an accidental commit of a copy of script/serve.sh. --- docs/script/serve.sh | 21 --------------------- 1 file changed, 21 deletions(-) delete mode 100755 docs/script/serve.sh diff --git a/docs/script/serve.sh b/docs/script/serve.sh deleted file mode 100755 index ae2615c..0000000 --- a/docs/script/serve.sh +++ /dev/null @@ -1,21 +0,0 @@ -# To override variables in _config.yml for use in your local environment, -# set those variables in _config_local.yaml. E.g. add a line like this to -# link to the root of the develop branch of the CTSIT fork: -# -# repo_root: https://github.com/ctsit/redcap_external_module_development_guide/tree/develop/ -# -# This script will load the contents of _config_local.yaml last if it exists. -# Github will only reference _config.yaml when building the site. - -# Note: You might need to tell rvm which ruby to use before running this script. e.g. -# -# rvm use 2.6.3 -# - -LOCAL_CONFIG_YAML=_config_local.yaml - -if [ -e ${LOCAL_CONFIG_YAML} ]; then - bundle exec jekyll serve --config _config.yml,${LOCAL_CONFIG_YAML} -else - bundle exec jekyll serve -fi From 292785d024a6fc605c44f565639ac617b773d60b Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Fri, 31 Jan 2020 14:07:45 -0500 Subject: [PATCH 32/77] 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 68973e2..0d7d410 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -114,7 +114,7 @@ Your new hire should not work alone. Connect them to the REDCap community. Sign Every software project needs a good home to be successful. The most foundational part of that home is _version control_. Version control software tracks the changes to files that make up a computer program, web site, documentation suite or _anything_. It documents the history of who did what when to which files. It documents the branching and rejoining any project experiences when there are multiple authors involved. -There are multiple version control packages to choose from, but the dominate player is _git_. It's high function, free, well-documented, works on the command line, and has multiple GUI interfaces. Git houses the software that runs the Internet. VUMC moved the REDCap code into git a few years back. They also require git for all modules submitted to the REDCap Repo. +There are multiple version control packages to choose from, but the dominant player is [_git_](https://git-scm.com/). It's high functioning, free, open source, well-documented, works on the command line, and has multiple GUI interfaces. Git houses the software that runs the Internet. VUMC moved the REDCap code into git a few years back. They also require git for all modules submitted to the REDCap Repo. Git stores the documents of a project in a repository or _repo_. Outwardly it looks like a folder full of files, but it contains a hidden folder that holds the entire history of the repository from creation to its current state. Every version of every file ever added to repository is in the hidden folder. Even deleted files are preserved there. This history records who made each revision, when they made the change and what other files changed at the same time. There's a description for each change as well. The history is immutable. You can't go back and pretend a change made 2 years ago didn't happen without rewriting all the history since then. From e2884ca8385f596a4256959d074254b296d06887 Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Fri, 31 Jan 2020 14:10:03 -0500 Subject: [PATCH 33/77] 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 0d7d410..184ec14 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -126,7 +126,7 @@ VUMC requires REDCap modules that want to be included in the REDCap Repo to be h Even without VUMC's requirement to use it, GitHub is still an excellent choice for hosting the development of a REDCap module or any software development project. GitHub's software enables a collaborative process of development for the software and its documentation. It allows anyone to participate as a peer in the process of creating, enhancing and maintaining a project. The service is free for public repos and it is centered around free tools. This zero cost for the tools of software development lowers potential barriers to entry for collaborators. -Easy paths to sharing the tools of clinical and translation research are important. In some cases, the funding sources for REDCap teams at academic health centers in the USA require sharing the works created with that funding. This is true of many NIH-funded projects and specifically the Clinical and Translational Science Awards (CTSAs) that fund many of the largest clinical research universities in the US. REDCap modules created at those institutions are one of those products that should be shared because of the funding sources. +Easy paths to sharing the tools of clinical and translation research are important. In some cases, the funding sources for REDCap teams at academic health centers in the USA require sharing the works created with that funding. This is true of many NIH-funded projects and specifically the Clinical and Translational Science Awards (CTSAs) that fund many of the largest clinical research universities in the US. REDCap modules created at those institutions are examples of products that should be shared because of the funding sources. Yet sharing a continually evolving product can be challenging. The pace of change in software development can leave fixes untested or not shared. Using a good hosting platform makes sharing and collaboration much simpler. GitHub provides tools and workflows to reduce the labor of sharing and more quickly and reliably deliver the latest iteration of a software package to those who need it. From ffd783bd24c7ac72c0eabfc5267b2337f1ce3ddf Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Fri, 31 Jan 2020 14:10:44 -0500 Subject: [PATCH 34/77] 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 184ec14..dde8121 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -124,7 +124,7 @@ One of the big players in source code hosting is [GitHub.com](https://github.com VUMC requires REDCap modules that want to be included in the REDCap Repo to be hosted in publicly-accessible software repositories on GitHub. This makes it simple for REDCap community members to share their work with both the VUMC REDCap team and the entire REDCap community. -Even without VUMC's requirement to use it, GitHub is still an excellent choice for hosting the development of a REDCap module or any software development project. GitHub's software enables a collaborative process of development for the software and its documentation. It allows anyone to participate as a peer in the process of creating, enhancing and maintaining a project. The service is free for public repos and it is centered around free tools. This zero cost for the tools of software development lowers potential barriers to entry for collaborators. +Even without VUMC's requirement to use it, GitHub is still an excellent choice for hosting the development of a REDCap module or any software development project. GitHub's software enables a collaborative process of development for the software and its documentation. It allows anyone to participate as a peer in the process of creating, enhancing and maintaining a project. The service is free for public repos and it is centered around free tools. The absence of a cost for the tools of software development lowers potential barriers to entry for collaborators. Easy paths to sharing the tools of clinical and translation research are important. In some cases, the funding sources for REDCap teams at academic health centers in the USA require sharing the works created with that funding. This is true of many NIH-funded projects and specifically the Clinical and Translational Science Awards (CTSAs) that fund many of the largest clinical research universities in the US. REDCap modules created at those institutions are examples of products that should be shared because of the funding sources. From 394f1e088a048c6f78136512ca289cc4c3f4f46e Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Sun, 2 Feb 2020 08:18:46 -0500 Subject: [PATCH 35/77] Update docs/guide_for_admins_and_devs.md fix case error in `eat` 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 dde8121..c1a3f52 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -142,7 +142,7 @@ Meanwhile, internal priorities have forced the private repo to evolve to meet lo The public repo remains a second class citizen forever. The consumers' questions annoy the developers because they already encountered those bugs and fixed them, but only in the local version. Porting those fixes into the public repo is always extra work. It grates on the developers' nerves. They grow to hate the public code and its consumers, but they never realize they are part of the problem. The developers' masters enjoy taking credit for sharing, but, with the developers talking about the additional labor of porting the local code to the public repo, they get the impression that sharing is expensive. They question the value of sharing without ever realizing they are part of the problem as well lowering the quality of what they share while increasing its cost. -The problem in this scenario is the authors of the software are not willing to use their own product. In the parlance of the software industry, they are unwilling to "Eat their own dog food". The author who won't use their own product, will never understand what is wrong with it and will never make it better. +The problem in this scenario is the authors of the software are not willing to use their own product. In the parlance of the software industry, they are unwilling to "eat their own dog food". The author who won't use their own product, will never understand what is wrong with it and will never make it better. To drive quality, the team should use its own product. To make the software portable, configurability should be baked in from the start. If the software is configurable from the beginning, there is no motivation to commit local configuration and secrets into the software. The test datasets the developers create to test their work should become part of the repo so other people can more rapidly test and demonstrate the software. To keep identifiable data out of the test data, developers should not be exposed to PHI or PII until they have demonstrated a respect for the risks it creates. If each of these rules is followed in writing the software, it will be ready for a public-facing repo on the day the project starts. From 3789c0984fc2ded14bb8516421afe66d6a44bfbd Mon Sep 17 00:00:00 2001 From: Philip Chase Date: Sun, 2 Feb 2020 18:50:24 -0500 Subject: [PATCH 36/77] Add sections to guide_for_admins_and_devs.md Add "Working as a team" to guide_for_admins_and_devs.md --- docs/guide_for_admins_and_devs.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/guide_for_admins_and_devs.md b/docs/guide_for_admins_and_devs.md index c1a3f52..a377bbe 100644 --- a/docs/guide_for_admins_and_devs.md +++ b/docs/guide_for_admins_and_devs.md @@ -147,3 +147,20 @@ The problem in this scenario is the authors of the software are not willing to u To drive quality, the team should use its own product. To make the software portable, configurability should be baked in from the start. If the software is configurable from the beginning, there is no motivation to commit local configuration and secrets into the software. The test datasets the developers create to test their work should become part of the repo so other people can more rapidly test and demonstrate the software. To keep identifiable data out of the test data, developers should not be exposed to PHI or PII until they have demonstrated a respect for the risks it creates. If each of these rules is followed in writing the software, it will be ready for a public-facing repo on the day the project starts. Yet there remains a tendency for people to think their code is not good enough to share. Nothing could be further from the truth. If the code works for the author, it is good enough to share. It might not work for the next person, but if they give feedback, their failure can help make the code better. Sharing early is always better. It makes better products. It lowers the cost of sharing. + + +## Working as a team + +Once the coding starts, REDCap Admins and developers have to work together on the common mission of making good REDCap modules. Github provides excellent tools to aid that collaboration. Those tools are well documented in the [GitHub Guides](https://guides.github.com/) The most important of these is [Understanding the GitHub flow](https://guides.github.com/introduction/flow/) as it teaches the concepts behind GitHub's tools. If you don't already know _Markdown_, also read [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) Markdown should be your go-to language for documenting your module from the `README.md` file to the text of Github issues and comments. Everyone--REDCap Admins and developer--should know the basics of Markdown. + +Every revision to a module should be reviewed by someone other than the person that did the work. The reviewer offers a different perspective on how the software should work, wether it works, if the documentation makes sense, or if the code is poorly written. A good testing workflow forces the author to commit changes into a git repo, while the tester checkouts out those changes and reviews the work in a different computer without asking the author questions. This makes sure the author put all the changes and any required documentation into the repo. + +The rule about using a different computer is *extremely* important. This will help the team avoid the dreaded "It works on my machine" syndrome when the module moves to production. Every member of the team can have their own "different computer" by using the [REDCap Docker Compose Environment](https://github.com/123andy/redcap-docker-compose). This software helps you build your own REDCap on your own computer. It's built on a technology called _Docker_ that allows a local REDCap host to be created in seconds. After that, a web-based installer allows a REDCap instance to be installed and confiugured in about a minute. The [Developer Guide](guide_for_devs/) builds upon this enviroment with +instructions for checking out a module to make it available to REDCap Docker Compose in [Setting Up Your Environment](guide_for_devs/#setting-up-your-environment). + +Every developer _must_ use REDCap Docker Compose or a similar local development environment to do their development and testing. It keeps them from placing a shared environment at risk and gives them the freedom to test different REDCap versions, different PHP versions, module upgrades, module re-enabling, create test users, etc. It will also make it difficult to hard-code facts about the production environment into the module. This will result in more-configurable, more portable modules that are easier to share both inside and outside the organization that wrote them. + +REDCap Admins would also be well-served to use a local REDCap. It will allow them to test module revisions earlier without any risks to a shared REDCap instance. This is especially important if there is only one developer on the team. _Someone_ needs to run the first _local_ test of the code. + +Wherever they test, REDCap Admins must test the new module before it is installed in production. They will have the best perspective on how it will integrate into the normal REDCap workflows. They will be the person who has to enable the module and configure it in production. If the admin is not they end user of the new module's features they will be charged with explaining it and/or documenting it for the REDCap users. The REDCap Admin will bear the burden of any failings in the module. + From 1b7255f6336c2d95e2874dcc54ec921ba8d18d3f Mon Sep 17 00:00:00 2001 From: Kyle Chesney Date: Mon, 3 Feb 2020 11:45:02 -0500 Subject: [PATCH 37/77] add introductory plugin exercise and documentation --- docs/guide_for_devs.md | 61 +++++++++++++++++++ exercises/README.md | 4 ++ exercises/intro_to_plugins/ExternalModule.php | 13 ++++ exercises/intro_to_plugins/README.md | 12 ++++ exercises/intro_to_plugins/config.json | 22 +++++++ .../pages/control_center_custom_page.php | 15 +++++ 6 files changed, 127 insertions(+) create mode 100644 exercises/intro_to_plugins/ExternalModule.php create mode 100644 exercises/intro_to_plugins/README.md create mode 100644 exercises/intro_to_plugins/config.json create mode 100644 exercises/intro_to_plugins/pages/control_center_custom_page.php diff --git a/docs/guide_for_devs.md b/docs/guide_for_devs.md index 0a49528..6e36126 100644 --- a/docs/guide_for_devs.md +++ b/docs/guide_for_devs.md @@ -137,3 +137,64 @@ function increase() {
+ +--- + +### [Hello Plugin]({{ site.repo_root }}exercises/intro_to_plugins/) + +This module introduces the use of plugins. The provided module already has a plugin page available for admins in the Control Center; the goal of this exercise is to add an additional plugin page accessible _at the project level_. Unlike other modules, you will need to create an entirely new PHP file for this project, referring to `pages/control_center_custom_page.php` should be useful. + +Read [the official documentation on creating plugin pages](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/official-documentation.md#how-to-create-plugin-pages-for-your-module). + +Icons can be set in a `link` object under `config.json` which will appear next to the link for a corresponding plugin page. In framework version >= 3, you have access to [Font Awesome](https://fontawesome.com/icons?d=gallery) icons. +When assigning icons, the entry will appear as follows: `fa