Merge branch 'release/1.0.0'

.gitignore

@@ -3,4 +3,5 @@ _site/
 .jekyll-cache/
 .jekyll-metadata
 Gemfile.lock
-*.gem
+*.gem
+_config_local.yaml

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change Log
+All notable changes to the REDCap External Module Development Guide project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+
+## [1.0.0] - 2020-02-24
+### Added
+- Initial release

docs/_config.yml

@@ -2,10 +2,17 @@ title: REDCap External Module Development Guide
 description: REDCap External Module Development Guide
 repository: ctsit/redcap_external_module_development_guide
 
-markdown: kramdown
+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
 theme: jekyll-theme-minimal
 logo: /assets/img/logo.png
 show_downloads: true
+authors:
+  - <a href="https://github.com/pbchase">Philip Chase</a>
+  - <a href="https://vivo.ufl.edu/display/n32455">Taryn Stoffs</a>
+  - <a href="https://github.com/ChemiKyle">Kyle Chesney</a>
+  - <a href="https://vivo.ufl.edu/display/n64866">Christopher P Barnes</a>
 google_analytics:

docs/_layouts/default.html

@@ -33,6 +33,15 @@ <h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repo
           <li><a href="{{ site.github.repository_url }}">View On <strong>GitHub</strong></a></li>
         </ul>
         {% endif %}
+
+        {% if site.authors.size > 0 %}
+        <p class="authors">Authors</p>
+        <ul class="authors">
+          {% for author in site.authors %}
+          <li>{{ author }}</li>
+          {% endfor %}
+        </ul>
+        {% endif %}
       </header>
       <section>
 

docs/_sass/em-guide.scss

@@ -0,0 +1,13 @@
+ul.authors {
+  list-style:none;
+  padding:0;
+}
+
+.authors li {
+  font-size:11px;
+}
+
+p.authors {
+  margin:0 0 3px;
+  font-weight:bold;
+}

docs/assets/css/style.scss

@@ -2,3 +2,4 @@
 ---
 
 @import "jekyll-theme-minimal";
+@import "em-guide";

docs/index.md

@@ -3,9 +3,8 @@ layout: default
 title: REDCap External Module Development Guide
 ---
 
-# REDCap External Module  Development Guide
+# REDCap External Module Development Guide
 
-This site is a guide to the development of software extensions to Vanderbilt University's Research Electronic Data CAPture (REDCap) using REDCap's External Module framework. Added to REDCap in the Fall of 2018, the external module framework has proven to be an effective an popular way to change REDCap's behavior to meet the needs of specific sites and projects. This guide provides an introduction to external modules and  guidance in creating a team and plan for developing modules for one's own needs and the larger REDCap community.
-
-The audience for this guide is both REDCap Admins and software developers who would be writing the modules. The guide is split into a two sections to address the different audiences. The first section, [REDCap External Module Development for REDCap Admins and Developers](guide_for_admins_and_devs), provides the background both audiences need to work together to create and share a module with the REDCap community. The second section, [REDCap External Module Development for Developers](guide_for_devs), provides guidance to developers on how to write the module code, REDCap classes, and resources for module development. The developer's guide is primarily composed of a series of exercises to create simple modules that extend REDCap in different ways.
+This site is a guide to the development of software extensions to Vanderbilt University's Research Electronic Data CAPture (REDCap) using REDCap's External Module framework. Added to REDCap in the Fall of 2017, the external module framework has proven to be an effective and popular way to change REDCap's behavior to meet the needs of specific sites and projects. This guide provides an introduction to external modules and guidance in creating a team and plan for developing modules for one's own needs and the broader REDCap community.
 
+The audience for this guide is both REDCap Admins and software developers who would be writing the modules. The guide is split into two sections to address the different audiences. The first section, [REDCap External Module Development for REDCap Admins and Developers](guide_for_admins_and_devs), provides the background both audiences need to work together to create and share a module with the REDCap community. The second section, [REDCap External Module Development for Developers](guide_for_devs), guides developers to the right development tools, suggests resources for module development and offers coding exercises to create simple modules that make use of the various tools at the disposal of an External Module developer.

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

exercises/README.md

@@ -0,0 +1,42 @@
+# 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.
+
+## 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/)
+
+### 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).
+
+### 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.
+
+## Hello Plugin
+
+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).
+
+## Accessing Variables
+
+Read [the official documentation on module functions](https://github.com/vanderbilt/redcap-external-modules/blob/testing/docs/framework/intro.md). Search for functions containing `User` and `ProjectSetting`.
+
+## Record Wrangling
+
+Read the source code of the following files (relative to the root of your `redcap_vx.y.z` folder), searching for phrases `getData`, `saveData`.
+- `ExternalModules/`
+    - `AbstractExternalModule.php`
+    - `ExternalModules.php`
+- `Classes/`
+    - `REDCap.php`
+    - `Records.php`

exercises/accessing_variables/ExternalModule.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace AccessingVariables\ExternalModule;
+
+use ExternalModules\AbstractExternalModule;
+
+class ExternalModule extends AbstractExternalModule {
+
+    //FIXME: Write and use functions to show users pertinent information
+
+}

exercises/accessing_variables/README.md

@@ -0,0 +1,12 @@
+# Accessing Variables
+
+Displays information relevant to users.
+
+## Prerequisites
+- 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 `<redcap-root>/modules/accessing_variables_v0.0.0`.
+- Go to **Control Center > Manage External Modules** and enable **Accessing Variables**.
+- For each project you want to use this module, go to the project home page, click on **Manage External Modules** link, and then enable **Accessing Variables** for that project.
+

exercises/accessing_variables/config.json

@@ -0,0 +1,13 @@
+{
+    "name": "Accessing Variables",
+    "description": "Module that describes users to themselves",
+    "namespace": "AccessingVariables\\ExternalModule",
+    "framework-version": 3,
+    "authors": [
+        {
+            "name": "Kyle Chesney",
+            "email": "[email protected]",
+            "institution": "University of Florida - CTSI"
+        }
+    ]
+}

exercises/hello_world_v0.0.0/ExternalModule.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace HelloWorld\ExternalModule;
+
+use ExternalModules\AbstractExternalModule;
+
+class ExternalModule extends AbstractExternalModule {
+
+    // This is generally where your module's hooks will live
+    function redcap_every_page_top($project_id) {
+        print_r('Hello world! I am a message produced by a hook!');
+    }
+
+}

exercises/hello_world_v0.0.0/README.md

@@ -0,0 +1,5 @@
+# Hello World
+
+Provides a page that says "Hello, world" in the control center and on projects.
+
+Shows admin view of a handful of configuration options.

exercises/hello_world_v0.0.0/config.json

@@ -0,0 +1,16 @@
+{
+    "name": "Hello world",
+    "description": "Hello world page to ensure your development tools are working",
+    "namespace": "HelloWorld\\ExternalModule",
+    "framework-version": 3,
+    "permissions": [
+        "redcap_every_page_top"
+    ],
+    "authors": [
+        {
+            "name": "Kyle Chesney",
+            "email": "[email protected]",
+            "institution": "University of Florida - CTSI"
+        }
+    ]
+}

exercises/intro_to_hooks/ExternalModule.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace HelloHook\ExternalModule;
+
+use ExternalModules\AbstractExternalModule;
+
+class ExternalModule extends AbstractExternalModule {
+
+    // Test out using the hooks in the documentation to make an alert appear in different contexts
+    // FIXME
+    /* Write your code here */
+    function a_real_redcap_hook() {
+    /* Stop writing code here */
+
+        // create an empty JS object for the module's variables
+        echo '<script>helloHook = {};</script>';
+        $this->setSingleJsSetting('message', 'Hello world!');
+        $this->includeJs('js/hello_hook.js');
+    }
+
+    protected function includeJs($file) {
+        // Use this function to use your JavaScript files in the frontend
+        echo '<script src="' . $this->getUrl($file) . '"></script>';
+    }
+
+    protected function setSingleJsSetting($key, $value) {
+        // Use this function to send variables to the frontend scoped within an object
+        echo '<script>helloHook.' . $key . '=' . json_encode($value) . ';</script>';
+    }
+}

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.3 (for versions < 8.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required).
+
+## Installation
+- Clone this repo into to `<redcap-root>/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 **Hello Hook** for that project.
+

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": "[email protected]",
+            "institution": "University of Florida - CTSI"
+        }
+    ]
+}

exercises/intro_to_hooks/js/hello_hook.js

@@ -0,0 +1,3 @@
+$( document ).ready(function() {
+    alert(helloHook.message);
+});

exercises/intro_to_js/ExternalModule.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace IntroJS\ExternalModule;
+
+use ExternalModules\AbstractExternalModule;
+use RCView;
+
+class ExternalModule extends AbstractExternalModule {
+
+    function redcap_project_home_page($project_id) {
+
+        // Define attributes for html elements
+        $button_attributes = [
+            'class' => '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 */
+    }
+
+}

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.3 (for versions < 8.0, [REDCap Modules](https://github.com/vanderbilt/redcap-external-modules) is required).
+
+## Installation
+- Clone this repo into to `<redcap-root>/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.
+

exercises/intro_to_js/config.json

@@ -0,0 +1,16 @@
+{
+    "name": "Intro JS",
+    "description": "Adds a counter to the project home page",
+    "namespace": "IntroJS\\ExternalModule",
+    "framework-version": 3,
+    "permissions": [
+        "redcap_project_home_page"
+    ],
+    "authors": [
+        {
+            "name": "Kyle Chesney",
+            "email": "[email protected]",
+            "institution": "University of Florida - CTSI"
+        }
+    ]
+}

exercises/intro_to_js/js/intro.js

@@ -0,0 +1,6 @@
+$( document ).ready(function() {
+    /* Write your code below */
+
+});
+
+/* If you wish, make a function */

exercises/intro_to_plugins/ExternalModule.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace HelloPlugin\ExternalModule;
+
+use ExternalModules\AbstractExternalModule;
+
+class ExternalModule extends AbstractExternalModule {
+
+    function sayHello() {
+        print_r("Hello, world!");
+    }
+
+}

exercises/intro_to_plugins/README.md

@@ -0,0 +1,12 @@
+# Hello Plugin
+
+Provides a page that says "Hello, world" in the control center.
+
+## Prerequisites
+- 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 `<redcap-root>/modules/intro_to_plugins_v0.0.0`.
+- Go to **Control Center > Manage External Modules** and enable **Hello Plugin**.
+- 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 Plugin** for that project.
+