Adds documentation to the existing Action Tags dialogue

HideSubmit.php

@@ -4,6 +4,47 @@
 
 class HideSubmit extends \ExternalModules\AbstractExternalModule {
 
+protected static $Tags = array(
+            '@HIDESUBMIT' => array('description'=>'HIDESUBMIT Action Tags<br/>Hides the Submit or Next Page button on a survey <em>and</em> all Save record buttons on a data entry form <em>if the field is visible due to branching logic</em>. <br/>Typically this action tag would be added to a descriptive text field that is displayed when some condition should prevent the respondent from submitting, or prevent the user from saving. E.g., \'Required fields missing!\' or \'Age must be greater than 18 years to continue\'.'),
+            '@HIDESUBMIT-FORM' => array('description'=>'HIDESUBMIT Action Tags<br/>Hides all Save record buttons on a data entry form <em>if the field is visible due to branching logic</em>. <br/>Typically this action tag would be added to a descriptive text field that is displayed when some condition should prevent the respondent from submitting, or prevent the user from saving. E.g., \'Required fields missing!\' or \'Age must be greater than 18 years to continue\'.'),
+            '@HIDESUBMIT-SURVEY' => array('description'=>'HIDESUBMIT Action Tags<br/>Hides the Submit or Next Page button on a survey <em>if the field is visible due to branching logic</em>. <br/>Typically this action tag would be added to a descriptive text field, and branched on some logic that should prevent the user from submitting the survey or saving the record. E.g., \'Required fields missing!\' or \'Age must be greater than 18 years to continue\'.'),
+        );
+
+protected function makeTagTR($tag, $description) {
+                global $isAjax, $lang;
+                return \RCView::tr(array(),
+			\RCView::td(array('class'=>'nowrap', 'style'=>'text-align:center;background-color:#f5f5f5;color:#912B2B;padding:7px 15px 7px 12px;font-weight:bold;border:1px solid #ccc;border-bottom:0;border-right:0;'),
+				((!$isAjax || (isset($_POST['hideBtns']) && $_POST['hideBtns'] == '1')) ? '' :
+					\RCView::button(array('class'=>'btn btn-xs btn-rcred', 'style'=>'', 'onclick'=>"$('#field_annotation').val(trim('".js_escape($tag)." '+$('#field_annotation').val())); highlightTableRowOb($(this).parentsUntil('tr').parent(),2500);"), $lang['design_171'])
+				)
+			) .
+			\RCView::td(array('class'=>'nowrap', 'style'=>'background-color:#f5f5f5;color:#912B2B;padding:7px;font-weight:bold;border:1px solid #ccc;border-bottom:0;border-left:0;border-right:0;'),
+				$tag
+			) .
+			\RCView::td(array('style'=>'line-height:1.3;font-size:13px;background-color:#f5f5f5;padding:7px;border:1px solid #ccc;border-bottom:0;border-left:0;'),
+				'<i class="fas fa-cube mr-1"></i>'.$description
+			)
+		);
+
+}
+
+public function redcap_every_page_before_render($project_id) {
+    if (PAGE==='Design/action_tag_explain.php') {
+        global $lang;
+        $lastActionTagDesc = end(\Form::getActionTags());
+
+        // which $lang element is this?
+        $langElement = array_search($lastActionTagDesc, $lang);
+
+        foreach (static::$Tags as $tag => $tagAttr) {
+            $lastActionTagDesc .= "</td></tr>";
+            $lastActionTagDesc .= $this->makeTagTR($tag, $tagAttr['description']);
+        }
+        $lang[$langElement] = rtrim(rtrim(rtrim(trim($lastActionTagDesc), '</tr>')),'</td>');
+    }
+}
+
+
     function getTags($tag) {
         // 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

README.md

@@ -1,6 +1,6 @@
 # HIDESUBMIT Action Tags
 
-This REDCap External Module allows users to conditionally hide the Submit/Next Page buttons on forms and/or surveys using action tags @HIDESUBMIT, @HIDESUBMIT-FORM and @HIDESUBMIT-SURVEY. If the relevant action tag is on any field that is visible on the current page due to branching logic, the Submit/Next Page button is hidden.
+This REDCap External Module allows users to conditionally hide the Submit/Next Page button and the 'Take Survey Again' button on surveys and the save buttons on forms (all of which I refer to as simple 'Submit') using action tags @HIDESUBMIT, @HIDESUBMIT-FORM and @HIDESUBMIT-SURVEY. If the relevant action tag is on any field that is visible on the current page due to branching logic, then all Submit/Next Page/Save (and...) buttons are hidden.
 
 The intention is that these action tags are used on descriptive text fields in which the respondent is informed that they cannot continue due to some reason. For example, a user could create a descriptive text field that shows a warning message such as "You appear to have missed some questions!", and use branching logic to display this field if any of the required fields on the page are empty. As a result of the @HIDESUBMIT action tags, the presence of this descriptive text field will prevent the submit button being displayed.
 
@@ -12,11 +12,19 @@ Once all descriptive text fields with @HIDESUBMIT are no longer visible (accordi
 
 ## Setup & Configuration
 
-Install the module from REDCap module repository and enable over Control Center.
+Install the module from the REDCap module repository and enable in the Control Center, then enable on projects.
 
 ## Usage and Examples
 
-The action tag can be added to any field, although descriptive text fields make the most sense. Hiding the submit button based on the visibility of a question field would be odd, since the response would not be able to be committed to the dataset.
+This module adds three action tags:
+
+- @HIDESUBMIT – Hides all save buttons on data entry forms and both the Submit/Next Page button and 'Take this survey again' button on surveys
+- @HIDESUBMIT-FORM – Hides all save buttons on data entry forms, and does not operate on surveys
+- @HIDESUBMIT-SURVEY – Hides the Submit/Next Page button and the 'Take this survey again' button on surveys, and does not operate on forms
+
+Thus, the conditional hiding of the submit buttons is as controllable by the project designer as standard branching logic.
+
+The action tags can be added to any field, although descriptive text fields make the most sense. Hiding the submit button based on the visibility of a question field would be odd, since the response would not be able to be committed to the dataset.
 
 ### Ensure all required fields are answered
 
@@ -28,10 +36,6 @@ To prevent a respondent prematurely submitting before all required fields are fi
 
 For a better respondent experience, this descriptive text field should inform them why they cannot proceed, in the example above, the field displays "You seem to have missed some required questions above!".
 
-### Enforcing survey quota
-
-Aggregate functions like `[aggregate-count:field]` (from v11.0.0) can be used to limit the survey to a certain number of respondents, hiding the submit button if the survey has fulfilled the quota and instead displaying a user-configurable warning such as "This survey is now closed".
-
 ### Minimum age
 
 A common use case is to limit a survey to respondents over a certain age. Traditionally, this is done using the survey queue. With @HIDESUBMIT this can be achieved using a descriptive text field and branching logic as follows:
@@ -41,22 +45,28 @@ datediff([dob],"today","y",true) < 18
 ```
 And thus prevents the creation of empty records.
 
-Note that the logic is reversed between @HIDESUBMIT and the survey queue approach; the survey queue will have the logic for respondents to continue (i.e. `datediff([dob],"today","y",true) >= 18`), whereas the @HIDESUBMIT field contains the logic used to prevent a respondent from continuing.
+Note that the logic between the survey queue approach and @HIDESUBMIT is reversed; the survey queue will be configured using the logic for respondents to continue (i.e. `datediff([dob],"today","y",true) >= 18`), whereas the @HIDESUBMIT field should use the logic that should prevent a respondent from continuing.
 
 ### Multiple exclusion factors
 
 Multiple @HIDESUBMIT fields are also possible. The submit button will be hidden if there are _any_ fields visible with the action tag. This allows users to construct eligibility surveys with multiple exclusion criteria.
 
+### Enforcing form statuses
+
+Project designers may wish to force their users to set data entry forms to complete status rather than unverified or incomplete. The complete status is available for branching logic, and thus can be used to display a warning message than contains @HIDESUBMIT-FORM. Require status to be set to complete using branching logic `[form-name_complete] <> 2` to display a descriptive text field annotated with @HIDESUBMIT. Using smart variables such as `[user-role-label]` in conjunction will allow projects to set up workflows, for example, the 'Data entry' role only being able to set form status to Unverified.
+
 ## TODO
 
-- Add action tag instructions to online designer dialogue
+- ~~Add action tag instructions to online designer dialogue~~ Added in v2.1.0
 
 ## Acknowledgements
 
-This is my first attempt at a REDCap External Module, and I borrowed heavily from other developers including Andy Martin, Ekin Tertemiz, Günther Rezniczek, as well as an earlier hook by Bob Gorczyca. I also drew on help with JavaScript from Luke Stevens, who also suggested the general design of this module.
+This is my first attempt at a REDCap External Module, and I borrowed heavily from other developers including Andy Martin, Ekin Tertemiz, Günther Rezniczek, as well as an earlier hook by Bob Gorczyca. I also drew on help with JavaScript from Luke Stevens, who also suggested the general design of this module. I also used Luke's code to augment the action tag help dialogue on designer pages (see [here](https://github.com/lsgs/redcap-date-validation-action-tags/blob/2d0cff6ad23f278d47decfcffe6478af212e6992/DateValidationActionTags.php#L36)), after a suggestion from Dan Foley.
 
 ## Changelog
 
-| Version | Description |
-| ------- | -------------------- |
-| v1.0.0  | Initial release. |
+| Version | Description                                                                              |
+| ------- | --------------------                                                                     |
+| v1.0.0  | Initial release.                                                                         |
+| v2.0.0  | Adds support for forms as well as surveys.                                               |
+| v2.1.0  | Adds documentation to Action Tag dialogue. Adds support for hiding survey repeat button. |

config.json

@@ -4,7 +4,8 @@
     "description": "Adds action tags @HIDESUBMIT, @HIDESUBMIT-SURVEY and @HIDESUBMIT-FORM, which allow users to conditionally hide the Submit/Next Page button/s on surveys and/or forms using. If the action tag is on any field that is visible on the current page due to branching logic, the Submit/Next Page buttons are hidden.",
     "permissions": [
         "redcap_survey_page_top",
-        "redcap_data_entry_form_top"
+        "redcap_data_entry_form_top",
+        "redcap_every_page_before_render"
     ],
     "framework-version": 6,
     "authors": [