Initial commit

.gitignore

@@ -0,0 +1,2 @@
+*.un~
+*.sw?

CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Wilson"
+  given-names: "Aidan"
+  orcid: "https://orcid.org/0000-0001-9858-5470"
+title: "Requested and Required Fields"
+doi: 
+date-released: 2024-06-17
+url: "https://github.com/jangari/redcap_requested_and_required_fields"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Aidan Wilson <aidan.wilson@intersect.org.au>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,49 @@
+# Requested and Required Fields
+
+This REDCap External Module provides functionality for requesting that respondents provide an answer to a field, and displays a warning to survey respondents if any requested fields are missing a value when they try to submit. For completeness, this module also allows required fields to be treated in the same way. Fields can be annotated with @REQUESTED or @REQUIRED, both of which take an optional description, which is shown to the user when they try to submit. If the description is omitted, the field label is shown instead.
+
+![screencast](screencast.gif)
+
+This module respects fields marked @HIDDEN(-SURVEY) and also those that are hidden due to branching logic.
+
+## Limitations
+
+This module does not play nicely with embedded fields. Perhaps this could be fixed, but at the moment it's just a limitation.
+
+Unlike traditional required fields, wherein submitting the page commits other values to the database and sets the survey as partially complete, with this module enabled, clicking 'submit' does _not_ save any other entered values. Again, perhaps this could be fixed by running an AJAX call to save the data.
+
+This module only considers fields to be required if they are annotated with @REQUIRED. It might be an idea in future to take fields marked Required in the designer and treat them in the same way. 
+
+## Installation
+
+Install the module from the REDCap module repository and enable in the Control Center, then enable on projects as needed.
+
+## Usage
+
+This module adds two action tags:
+
+| Action Tag | Description |
+| --- | --- |
+| @REQUESTED | Displays a modal window if the annotated field is empty when the respondent attempts to submit, but allows the respondent to submit regardless (unless there are @REQUIRED fields). With a description provided by @REQUESTED="description", the description is shown in the modal. Otherwise, the field label is shown. |
+| @REQUIRED | Displays a modal window if the annotated field is empty when the respondent attempts to submit, and prevents submission. With a description provided by @REQUIRED="description", the description is shown in the modal. Otherwise, the field label is shown. |
+
+## Configuration
+
+This module can be configured with the following project settings:
+
+| Setting | Default Value | Description |
+| --- | --- | --- |
+| Modal title | "Action Required!" | Title of the popup window showing any requested or required fields. |
+| Requested text |  "The following fields are requested, although you may submit without completing them:" | Text displayed in the modal window above listed requested fields. |
+| Required text |  "The following fields are required:" | Text displayed in the modal window above listed requested fields. |
+| Footer text (no required fields) |  "The following fields are requested, although you may submit without completing them:" | Text displayed at the end of the modal, above the buttons, where no required fields are missing. |
+| Footer text (required fields) |  "The following fields are required:" | Text displayed at the end of the modal, above the buttons, where required fields are missing. |
+| Cancel button text | "Review Response" | Text for cancel button. |
+| Submit button text | "Submit Now" | Text for submit button. |
+| Highlight fields after displaying warning? | false | If true, highlights required and requested fields after cancelling the modal window. |
+| Highlight colour for requested fields | "#d2e0ff" (light blue) | Colour used to highlight requested fields. |
+| Highlight colour for required fields | "#ffd2e0" (light red) | Colour used to highlight required fields. |
+| Disable green highlight | false | Disable the default green highlighting on all fields, as this will visually conflict with the highlighting added by this module. |
+| Label requested fields | false | Display a label on requested fields. |
+| Requested field label text | "* response requested" | Text for requested field label. |
+| Requested field label colour | "#0000ff" (blue) | Colour for requested field label. |

RequestedAndRequiredFields.php

@@ -0,0 +1,271 @@
+<?php namespace INTERSECT\RequestedAndRequiredFields;
+
+use \REDCap as REDCap;
+use ExternalModules\AbstractExternalModule;
+
+class RequestedAndRequiredFields extends \ExternalModules\AbstractExternalModule {
+
+    function getTags($tags, $fields, $instruments) {
+        // This is straight out of Andy Martin's example post on this:
+        // https://community.projectredcap.org/questions/32001/custom-action-tags-or-module-parameters.html
+        if (!class_exists('INTERSECT\RequestedAndRequiredFields\ActionTagHelper')) include_once('classes/ActionTagHelper.php');
+        $action_tag_results = ActionTagHelper::getActionTags($tags, $fields, $instruments);
+        return $action_tag_results;
+    }
+
+    function redcap_survey_page($project_id, $record, $instrument) {
+
+		// Get all annotated fields
+        $requestedTag = "@REQUESTED";
+        $requiredTag = "@REQUIRED";
+		$tags = array($requestedTag, $requiredTag);
+        $annotatedFields = $this->getTags($tags, $fields=NULL, $instruments=$instrument);
+
+        // Extract field names and build the new structure, with fieldType and description (or label if unset in the tag)
+        $requestedFields = [];
+        foreach (array_keys($annotatedFields[$requestedTag]) as $fieldName) {
+                $fieldType = REDCap::getFieldType($fieldName);
+                $description = trim($annotatedFields[$requestedTag][$fieldName][0], '"');
+				if (strlen($description) == 0) $description = $this->getFieldLabel($fieldName);
+                $requestedFields[$fieldName] = [
+                    'type' => $fieldType,
+                    'description' => $this->escape($description)
+                ];
+        };
+        $requiredFields = [];
+        foreach (array_keys($annotatedFields[$requiredTag]) as $fieldName) {
+                $fieldType = REDCap::getFieldType($fieldName);
+                $description = trim($annotatedFields[$requiredTag][$fieldName][0], '"');
+				if (strlen($description) == 0) $description = $this->getFieldLabel($fieldName);
+                $requiredFields[$fieldName] = [
+                    'type' => $fieldType,
+                    'description' => $this->escape($description)
+                ];
+        };
+
+		// Collect project settings
+		$settings = $this->getProjectSettings();
+
+		// Language defaults
+		$settings['modal-title'] = $settings['modal-title'] ?? $this->tt('modal-title-text');
+		$settings['modal-requested-header'] = $settings['modal-requested-header'] ?? $this->tt('modal-requested-header-text');
+		$settings['modal-required-header'] = $settings['modal-required-header'] ?? $this->tt('modal-required-header-text');
+		$settings['modal-footer-norequired'] = $settings['modal-footer-norequired'] ?? $this->tt('modal-footer-norequired-text');
+		$settings['modal-footer-required'] = $settings['modal-footer-required'] ?? $this->tt('modal-footer-required-text');
+		$settings['requested-label'] = $settings['requested-label'] ?? $this->tt('requested-label-text');
+		$settings['modal-cancel'] = $settings['modal-cancel'] ?? $this->tt('modal-cancel-text');
+		$settings['modal-submit'] = $settings['modal-submit'] ?? $this->tt('modal-submit-text');
+
+		// Colour defaults
+		$settings['requested-hlcolour'] = $settings['requested-hlcolour'] ?? $this->tt('requested-hlcolour-hex');
+		$settings['required-hlcolour'] = $settings['required-hlcolour'] ?? $this->tt('required-hlcolour-hex');
+		$settings['requested-label-colour'] = $settings['requested-label-colour'] ?? $this->tt('requested-label-colour-hex');
+
+        echo "<script>
+            $('button[name=\"submit-btn-saverecord\"]').attr('onclick','$(this).button(\"disable\");checkReqdFields();return false;');
+            var requestedFields = " . json_encode($requestedFields) . ";
+            var requiredFields = " . json_encode($requiredFields) . ";
+            $.each(requestedFields, function(fieldName, fieldInfo) {
+                var fieldRow = $('tr#'+fieldName+'-tr');
+                var fieldType = fieldInfo.type;
+                var desc = fieldInfo.description;
+                if (!fieldRow.length) {
+                    delete requestedFields[fieldName];
+                }
+                var fieldClass = fieldRow.attr('class');
+                if (fieldClass && fieldClass.indexOf('@HIDDEN') !== -1) {
+                    delete requestedFields[fieldName];
+                }
+            });
+            $.each(requiredFields, function(fieldName, fieldInfo) {
+                var fieldRow = $('tr#'+fieldName+'-tr');
+                var fieldType = fieldInfo.type;
+                var desc = fieldInfo.description;
+                if (!fieldRow.length) {
+                    delete requiredFields[fieldName];
+                }
+                var fieldClass = fieldRow.attr('class');
+                if (fieldClass && fieldClass.indexOf('@HIDDEN') !== -1) {
+                    delete requiredFields[fieldName];
+                }
+            });
+            function fieldIsEmpty(fieldName, fieldType){
+                var fieldIsEmpty = false;
+                var fieldRow = $('tr#'+fieldName+'-tr');
+                if (!fieldRow.is(':visible')) {
+                    return fieldIsEmpty;
+                }
+                switch (fieldType) {
+                    case 'text':
+                    case 'radio':
+                    case 'truefalse':
+                    case 'yesno':
+                    case 'slider':
+                    case 'file':
+                    case 'signature':
+                        fieldIsEmpty = ($('input[name=\"'+fieldName+'\"]').val()==='');
+                        break;
+                    case 'notes':
+                        fieldIsEmpty = ($('textarea[name=\"'+fieldName+'\"]').val()==='');
+                        break;
+                    case 'dropdown':
+                    case 'sql':
+                        fieldIsEmpty = ($('select[name=\"'+fieldName+'\"]').val()==='');
+						break;
+					case 'checkbox':
+						fieldIsEmpty = (!$('tr#' + fieldName+ '-tr').find('input[type=\"checkbox\"]').is(':checked'));
+						break;
+                }
+                return fieldIsEmpty;
+            }
+            function createEmptyReport(fieldArray){
+                var empties = [];
+                $.each(fieldArray, function(fieldName, fieldInfo) {
+                    var fieldType = fieldInfo.type;
+                    var fieldDesc = fieldInfo.description;
+                    if (fieldIsEmpty(fieldName, fieldType)) {
+                        empties.push(fieldDesc);
+                    }
+                });
+                return empties;
+            };
+			function addClassToField(fieldName, className){
+                var fieldRow = $('tr#'+fieldName+'-tr');
+				fieldRow.addClass(className);
+			};
+            function checkReqdFields(){
+				$('#requested-list').empty();
+				$('#required-list').empty();
+                var emptyRequested = createEmptyReport(requestedFields);
+                var emptyRequired = createEmptyReport(requiredFields);
+                if (emptyRequested.length + emptyRequired.length == 0){
+                    dataEntrySubmit();
+                } else {
+					if (emptyRequested.length > 0) {
+						$('#modal-requested-header').show();
+						// Re-enable the modal's submit button
+						$('button#confirmSubmit').prop('disabled', false);
+						// Create a <ul> element
+						var requestedUl = document.createElement('ul');
+						// Loop through the descriptions and create <li> elements
+						emptyRequested.forEach(function(description) {
+							var li = document.createElement('li');
+							li.textContent = description;
+							requestedUl.appendChild(li);
+						});
+						document.getElementById('requested-list').appendChild(requestedUl);
+					} else {
+						$('#modal-requested-header').hide();
+					}
+					if (emptyRequired.length > 0) {
+						$('#modal-required-header').show();
+						// Disable modal's submit button
+						$('button#confirmSubmit').prop('disabled', true);
+						$('#modal-action').text('". $settings['modal-footer-required']  ."');
+						// Create a <ul> element
+						var requiredUl = document.createElement('ul');
+						// Loop through the descriptions and create <li> elements
+						emptyRequired.forEach(function(description) {
+							var li = document.createElement('li');
+							li.textContent = description;
+							requiredUl.appendChild(li);
+						});
+						document.getElementById('required-list').appendChild(requiredUl);
+					} else {
+						$('#modal-required-header').hide();
+					}
+
+					// Show modal
+					$('#confirmationModal').modal('show');
+					// Handle the OK button click in the modal
+					$('button#confirmSubmit').on('click', function() {
+						// Hide the modal
+						$('#confirmationModal').modal('hide');
+						// Call the original function
+						dataEntrySubmit();
+					});
+					// Handle the Cancel button click in the modal
+					$('#cancelSubmit, .close').on('click', function() {
+						// Re-enable the submit button
+						$('#confirmationModal').modal('hide');
+						$('button[name=\"submit-btn-saverecord\"]').button('enable')
+						$.each(requestedFields, function(fieldName) {
+							addClassToField(fieldName, 'em-requested');
+						});
+						$.each(requiredFields, function(fieldName) {
+							addClassToField(fieldName, 'em-required');
+						});
+					});
+					// Re-enable the submit button if the modal is closed without confirmation
+					$('#confirmationModal').on('hidden.bs.modal', function () {
+						$('button[name=\"submit-btn-saverecord\"]').button('enable')
+						$.each(requestedFields, function(fieldName) {
+							addClassToField(fieldName, 'em-requested');
+						});
+						$.each(requiredFields, function(fieldName) {
+							addClassToField(fieldName, 'em-required');
+						});
+					});
+                }
+            };
+		</script>";
+
+		if ($settings['highlight']) {
+			echo "<style>
+				tr.em-requested .labelrc, tr.em-requested .data {
+					background: " . $settings['requested-hlcolour'] . ";
+				}
+				tr.em-required .labelrc, tr.em-required .data {
+					background: " . $settings['required-hlcolour'] . ";
+				}
+			</style>";
+		}
+
+		echo "<div class='modal fade' id='confirmationModal' tabindex='-1' role='dialog' aria-labelledby='confirmationModalLabel' aria-hidden='true'>
+				<div class='modal-dialog' role='document'>
+					<div class='modal-content'>
+						<div class='modal-header'>
+							<h5 class='modal-title' id='confirmationModalLabel'>".$settings['modal-title']."</h5>
+							<button type='button' class='close' data-dismiss='modal' aria-label='Close'>
+								<span aria-hidden='true'>&times;</span>
+							</button>
+						</div>
+						<div class='modal-body'>
+							<p id='modal-requested-header'>".$settings['modal-requested-header']."</p>
+							<div " . ($settings['highlight'] ? "style='background: " . $settings['requested-hlcolour'] . ";'" : "") . " id='requested-list'></div>
+							<p id='modal-required-header'>".$settings['modal-required-header']."</p>
+							<div " . ($settings['highlight'] ? "style='background: " . $settings['required-hlcolour'] . ";'" : "") . " id='required-list'></div>
+							<p id='modal-action'>".$settings['modal-footer-norequired']."</p>
+						</div>
+						<div class='modal-footer'>
+							<button type='button' class='btn btn-secondary' data-dismiss='modal' id='cancelSubmit'>".$settings['modal-cancel']."</button>
+							<button type='button' class='btn btn-primary' id='confirmSubmit'>".$settings['modal-submit']."</button>
+						</div>
+					</div>
+				</div>
+			</div>";
+		if ($settings['show-requested']) {
+			echo "<script>
+				var requestedLabelDiv = '<div class=\"requestedlabel\" aria-label=\"response requested\">" . $settings['requested-label'] . "</div>';
+				document.addEventListener('DOMContentLoaded', function() {
+					$.each(requestedFields, function(fieldName) {
+						var fieldRow = $('tr#'+fieldName+'-tr');
+						fieldRow.find('label#label-' + fieldName + ' div[data-mlm-field=\"' + fieldName + '\"]').append(requestedLabelDiv);
+					});
+				});
+				</script>
+				<style>
+					.requestedlabel {
+						font-size: 12px;
+						color: " . $settings['requested-label-colour'] . ";
+						font-weight: normal;
+					}
+				</style>";
+		}
+		if ($settings['disable-greenhl']) {
+		echo "<script>
+				doGreenHighlight = function() {};
+			</script>";
+		}
+    }
+}