Added documentation and help

RedCapEtlModule.php

@@ -18,7 +18,8 @@ class RedCapEtlModule extends \ExternalModules\AbstractExternalModule
  const USER_CONFIG_PAGE = 'web/admin/user_config.php';
  const SERVERS_PAGE = 'web/admin/servers.php';
  const SERVER_CONFIG_PAGE = 'web/admin/server_config.php';
-
+ const ADMIN_INFO_PAGE = 'web/admin/info.php';
+
  const USER_ETL_CONFIG_PAGE = 'web/configure.php';
 
  const RUN_LOG_ACTION = 'REDCap-ETL Export';
@@ -573,13 +574,16 @@ public function renderAdminTabs($activeUrl = '')
  .' User Config</span>';
 
  $serversUrl = $this->getUrl(self::SERVERS_PAGE);
- $serversLabel = '<span class="glyphicon glyphicon-cog" aria-hidden="true"></span>'
+ $serversLabel = '<span class="glyphicon glyphicon-list" aria-hidden="true"></span>'
  .' ETL Servers';
 
  $serverConfigUrl = $this->getUrl(self::SERVER_CONFIG_PAGE);
  $serverConfigLabel = '<span class="glyphicon glyphicon-cog" aria-hidden="true"></span>'
  .' ETL Server Config';
 
+ $helpUrl = $this->getUrl(self::ADMIN_INFO_PAGE);
+ $helpLabel = '&nbsp;<span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span>&nbsp;';
+
  $tabs = array();
 
  $tabs[$adminUrl] = $adminLabel;
@@ -590,6 +594,8 @@ public function renderAdminTabs($activeUrl = '')
  $tabs[$serversUrl] = $serversLabel;
  $tabs[$serverConfigUrl] = $serverConfigLabel;
 
+ $tabs[$helpUrl] = $helpLabel;
+
  $this->renderTabs($tabs, $activeUrl);
  }
 

classes/Help.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace IU\RedCapEtlModule;
+
+class Help
+{
+ /** @var array map from help topic to help content */
+ private static $info =
+ ['test' => 'This is a test'.'.']
+ ;
+
+ public static function getHelp($topic)
+ {
+ return self::$info[$topic];
+ }
+}
+
+
+print Help::getHelp('test')."\n";
+

classes/Settings.php

@@ -12,6 +12,7 @@ class Settings
  const LAST_RUN_TIME_KEY = 'last-run-time'; // for storing day and time of last run
 
  const USER_PROJECTS_KEY_PREFIX = 'user-projects:'; // appdend with username to make key
+ const HELP_KEY_PREFIX = 'help:'; // append with help topic to make key
 
  const CONFIG_SESSION_KEY = 'redcap-etl-config';
 
@@ -824,4 +825,29 @@ public function isLastRunTime($date, $time)
  $lastRunTime = $this->getLastRunTime();
  return $lastRunTime[0] == $date && $lastRunTime[1] == $time;
  }
+
+
+ #--------------------------------------------------------------
+ # Help settings methods, for custom, site-specific, help
+ #--------------------------------------------------------------
+
+ public function getHelp($topic)
+ {
+ $key = self::HELP_KEY_PREFIX . $topic;
+ $help = $this->module->getSystemSetting($key);
+ return $help;
+ }
+
+ public function setHelp($topic, $help)
+ {
+ $key = self::HELP_KEY_PREFIX . $topic;
+ $this->module->setSystemSetting($key, $help);
+ }
+
+ public function removeHelp($topic)
+ {
+ $key = self::HELP_KEY_PREFIX . $topic;
+ $this->module->removeSystemSetting($key);
+ }
+
 }

web/admin/info.php

@@ -0,0 +1,84 @@
+<?php
+
+/** @var \IU\RedCapEtlModule\RedCapEtlModule $module */
+
+if (!SUPER_USER) {
+ exit("Only super users can access this page!");
+}
+
+require_once __DIR__.'/../../dependencies/autoload.php';
+
+use \IU\REDCapETL\Version;
+
+use \IU\RedCapEtlModule\AdminConfig;
+use \IU\RedCapEtlModule\Filter;
+use \IU\RedCapEtlModule\RedCapEtlModule;
+
+$selfUrl = $module->getUrl(RedCapEtlModule::ADMIN_INFO_PAGE);
+$configUrl = $module->getUrl(RedCapEtlModule::ADMIN_HOME_PAGE);
+$usersUrl = $module->getUrl(RedCapEtlModule::USERS_PAGE);
+
+$cronDetailUrl = $module->getUrl(RedCapEtlModule::CRON_DETAIL_PAGE);
+
+$adminConfig = $module->getAdminConfig();
+
+$redcapEtlImage = $module->getUrl('resources/redcap-etl.png');
+
+
+?>
+
+<?php #include APP_PATH_DOCROOT . 'ControlCenter/header.php'; ?>
+
+<?php
+#---------------------------------------------
+# Include REDCap's control center page header
+#---------------------------------------------
+ob_start();
+include APP_PATH_DOCROOT . 'ControlCenter/header.php';
+$buffer = ob_get_clean();
+$cssFile = $module->getUrl('resources/redcap-etl.css');
+$link = '<link href="'.$cssFile.'" rel="stylesheet" type="text/css" media="all">';
+$buffer = str_replace('</head>', " ".$link."\n</head>", $buffer);
+echo $buffer;
+?>
+
+<h4><img style="margin-right: 7px;" src="<?php echo APP_PATH_IMAGES ?>table_gear.png">REDCap-ETL Admin</h4>
+
+
+<?php
+
+$module->renderAdminPageContentHeader($selfUrl, $error, $success);
+
+?>
+
+<?php
+#print "<pre>POST:\n"; print_r($_POST); print "</pre>\n";
+?>
+
+<p>
+The REDCap-ETL (Extract Transform Load) external module:
+<ol>
+ <li>Extracts data from REDCap</li>
+ <li>Transforms data based on user-specified transformation rules</li>
+ <li>Loads transformed data into a database</li>
+</ol>
+</p>
+
+<p>
+<img src="<?php echo $redcapEtlImage; ?>">
+</p>
+
+REDCap-ETL has the following admin pages:
+<ul>
+ <li><a href="<?php echo $configUrl;?>" style="font-weight: bold;">Config</a>
+ - General REDCap-ETL configuration with information on number and time of crom (scheduled) ETL jobs.
+ </li>
+ <li><a href="<?php echo $cronDetailUrl;?>" style="font-weight: bold;">Cron Detail</a>
+ - Detailed information on cron (scheduled) ETL jobs.
+ </li>
+ <li><a href="<?php echo $usersUrl;?>" style="font-weight: bold;">Users</a>
+ - List of users who have been given permission to use REDCap-ETL.
+ </li>
+</ul> 
+
+<?php include APP_PATH_DOCROOT . 'ControlCenter/footer.php'; ?>

web/help.php

@@ -0,0 +1,192 @@
+<?php
+
+/** @var \IU\RedCapEtlModule\RedCapEtlModule $module */
+
+require_once __DIR__.'/../dependencies/autoload.php';
+
+use IU\RedCapEtlModule\Filter;
+
+#-----------------------------------------------------------------
+# Process form submissions (configuration add/copy/delete/rename)
+#-----------------------------------------------------------------
+$submitValue = $_POST['submitValue'];
+if (strcasecmp($submitValue, 'add') === 0) {
+ #--------------------------------------
+ # Add configuration
+ #--------------------------------------
+ if (!array_key_exists('configurationName', $_POST) || empty($_POST['configurationName'])) {
+ $error = 'ERROR: No configuration name was specified.';
+ } else {
+ try {
+ $configurationName = $_POST['configurationName'];
+ $configuration = $module->getConfiguration($configurationName);
+ if (isset($configuration)) {
+ $error = 'ERROR: configuration "'.$configurationName.'" already exists.';
+ } else {
+ $indexUrl = $module->getUrl("web/index.php");
+ $module->addConfiguration($configurationName);
+ header('Location: '.$indexUrl);
+ }
+ } catch (\Exception $exception) {
+ $error = 'ERROR: '.$exception->getMessage();
+ }
+ }
+}
+
+
+require_once APP_PATH_DOCROOT . 'Config/init_global.php';
+
+// Initialize page display object
+$objHtmlPage = new HtmlPage();
+$objHtmlPage->addExternalJS(APP_PATH_JS . "base.js");
+$objHtmlPage->addStylesheet("jquery-ui.min.css", 'screen,print');
+$objHtmlPage->addStylesheet("style.css", 'screen,print');
+$objHtmlPage->addStylesheet("home.css", 'screen,print');
+$objHtmlPage->PrintHeader();
+
+include APP_PATH_VIEWS . 'HomeTabs.php';
+
+
+#---------------------------------------------
+# Add custom files to head section of page
+#---------------------------------------------
+###ob_start();
+###include APP_PATH_DOCROOT . 'ProjectGeneral/header.php';
+###$buffer = ob_get_clean();
+###$cssFile = $module->getUrl('resources/redcap-etl.css');
+###$link = '<link href="'.$cssFile.'" rel="stylesheet" type="text/css" media="all">';
+###$buffer = str_replace('</head>', " ".$link."\n</head>", $buffer);
+
+#$buffer = $module->renderProjectPageHeader();
+###echo $buffer;
+?>
+
+<div class="projhdr">
+<img style="margin-right: 7px;" src="<?php echo APP_PATH_IMAGES ?>database_table.png">REDCap-ETL
+</div>
+
+<h1>HELP</h1>
+
+<?php
+
+$configurationNames = $module->getConfigurationNames();
+
+$adminConfig = $module->getAdminConfig();
+
+$selfUrl = $module->getUrl('web/help.php');
+
+
+?>
+
+
+
+<?php
+
+#--------------------------------------------------------------------
+# If the user does NOT have permission to use ETL for this project,
+# display a link to send e-mail to request access
+#--------------------------------------------------------------------
+if (!SUPER_USER && !in_array($projectId, $userEtlProjects)) {
+ echo '<div style="padding-top:15px; padding-bottom:15px;">'."\n";
+ $label = 'Request ETL access for this project';
+
+ # The underscore variable names are internal REDCap variables
+ // phpcs:disable
+ $homepageContactEmail = $homepage_contact_email;
+ $redcapVervaion = $redcap_version;
+ $userFirstName = $user_firstname;
+ $userLastName = $user_lastname;
+ // phpcs:enable
+
+ echo '<a href="mailto:'.$homepageContactEmail
+ .'?subject='.rawurlencode('REDCap-ETL Access Request')
+ .'&body='
+ .rawurlencode(
+ 'Username: '.USERID."\n"
+ .'Project title: "'.' '.strip_tags(REDCap::getProjectTitle()).'"'."\n"
+ .'Project link: '.APP_PATH_WEBROOT_FULL."redcap_v{$redcapVersion}/index.php?pid={$projectId}\n\n"
+ .'Dear REDCap administrator,'."\n\n"
+ .'Please add REDCap-ETL access for me to project "'.REDCap::getProjectTitle().'"'."\n\n"
+ ."Sincerely,\n"
+ .$userFirstName.' '.$userLastName
+ )
+ .'" '
+ .' class="btn-contact-admin btn btn-primary btn-xs" style="color:#fff;">'
+ .'<span class="glyphicon glyphicon-envelope"></span> '.$label
+ .'</a>'."\n";
+ ;
+ echo "</div>\n";
+} else {
+?>
+
+<?php
+#------------------------------------------------------------
+# Add configuration form
+#------------------------------------------------------------
+?>
+<form action="<?=$selfUrl;?>" method="post" style="margin-bottom: 12px;">
+ REDCap-ETL configuration name:
+ <input name="configurationName" type="text" size="40" />
+ <input type="submit" name="submitValue" value="Add" />
+</form>
+
+<?php
+}
+?>
+
+<?php
+#--------------------------------------
+# Delete config dialog
+#--------------------------------------
+?>
+<script>
+$(function() {
+ // Delete ETL configuration form
+ deleteForm = $("#deleteForm").dialog({
+ autoOpen: false,
+ height: 170,
+ width: 400,
+ modal: true,
+ buttons: {
+ Cancel: function() {$(this).dialog("close");},
+ "Delete configuration": function() {deleteForm.submit();}
+ },
+ title: "Delete configuration"
+ });
+
+ <?php
+ # Set up click event handlers for the Delete Configuration buttons
+ $row = 1;
+ foreach ($configurationNames as $configurationName) {
+ echo '$("#deleteConfig'.$row.'").click({configName: "'
+ .Filter::escapeForJavaScriptInDoubleQuotes($configurationName)
+ .'"}, deleteConfig);'."\n";
+ $row++;
+ }
+ ?>
+
+ function deleteConfig(event) {
+ var configName = event.data.configName;
+ $("#configToDelete").text('"'+configName+'"');
+ $('#deleteConfigName').val(configName);
+ $("#deleteForm").dialog("open");
+ }
+});
+</script>
+<div id="deleteDialog"
+ title="Configuration Delete"
+ style="display: none;"
+ >
+ <form id="deleteForm" action="<?php echo $selfUrl;?>" method="post">
+ To delete the ETL configuration <span id="configToDelete" style="font-weight: bold;"></span>,
+ click on the <span style="font-weight: bold;">Delete configuration</span> button.
+ <input type="hidden" name="deleteConfigName" id="deleteConfigName" value="">
+ <input type="hidden" name="submitValue" value="delete">
+ </form>
+</div>
+
+
+
+<?php include APP_PATH_DOCROOT . 'ProjectGeneral/footer.php'; ?>
+
+